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外 延 丰 富 / 有 业务 含义 的 术语 翻译 : 直译 、 保 留 原 
文 、 词 汇 表 


一 些 术 语 难 翻 的 点 可 能 有 以 下 各 个 方面 ， 比 如 : 


© 具有 宽泛 的 外 延 / 内 涵 / 比 喻 义 /象征 义 / 指 代 义 (比如 requestiresponse， 有 时 指 一 个 HTTP 
层面 的 请 求 ， 有 时 指 一 个 应 用 层级 的 请 求 ， 有 时 又 特 指 一 个 请 求 对 象 ， 有 时 又 具体 到 特 
定 类 型 uttpservletRequest 请 求 对 象 中 的 内 容 或 请 求 头等 ， 又 比如 mapping， 可 以 动词 映 
射 ， 也 可 以 是 名 词 什么 什么 映射 ， 有 时 它 还 可 以 省 略 映射 的 目标 或 源 对 象 ) 

e 具有 相对 自治 、 完 整 的 业务 含义 〈 比 如 scope、action、bean、flashmap、multipart ` 
session/conversation 等 ) ， 而 该 业务 领域 在 中 文 技术 世界 又 尚 无 对 应 词汇 


目前 大 致 的 处 理 方式 是 : 


。 对 于 其 外 延 义 尚 可 翻 (只 是 中 文 语意 承载 量 仍然 不 足 ) 的 单词 ， 采 用 直译 + 词汇 表 的 翻 
译 。 词 汇 表 即 是 鼠标 划 过 停留 时 ， 会 显示 额外 的 提示 信息 ， 在 提示 里 更 详细 地 解释 这 个 
词 在 英文 中 的 完整 含义 ) 

e 对 于 业务 含义 较 完 备 ， 且 深刻 体现 在 代码 或 命名 中 实在 没 法 翻 的 单词 ， 采 用 保留 原文 + 词 
LR 的 方式 翻译 


未 决 翻 译 


e locales : 本 地 化 ?地 区 ? 

e multipart: 多 部 分 (这 是 中 文 ) ?多 路 ? 

e flashmap : 我 彻底 地 懂 了 。 不 知道 怎么 翻 好 ， 可 能 需要 查 一 下 TCP/IP 这 一 块 的 名 词 ， 看 
看 有 没有 什么 专业 字 词 能 够 体现 、 概 括 的 


TODOLIST 


。 翻译 怎么 样 算 好 ? 具体 到 技术 翻译 这 个 上 下 文 ， 全 部 照 翻 为 好 ? 谁 都 能 意识 到 要 适当 变 
通 ， 可 变通 的 度 是 多 少 ? 如 果 要 求 的 是 字 字 都 有 对 应 译 ， 还 要 符合 中 文风 格 ， 那 此 种 翻 
译 岂 非 只 在 寻求 一 个 可 能 存在 的 “ 解 "而 失去 任何 可 能 的 发 挥 ? 如果 要 求 的 是 信 达 的 同时 可 
以 体现 风格 ， 强 调 内 在 和 谐 胜 于 字句 适 配 ， 那 么 风格 的 适当 与 否 评 价 标准 又 在 哪里 ? 译 
者 和 作者 的 关系 是 怎样 的 ? 


21.1 Spring Web MVC 框 架 简介 


Spring 的 模型 -视图 制 器 (MVC) 框架 是 围绕 一 个 DispatcherServlet 来 设计 的 ， 这 个 
Servlet 会 把 请 求 分 发 给 各 个 处 理 器 ， 并 支持 可 配置 的 处 理 器 映射 、 视 图 泻 染 、 本 地 化 、 时 区 
与 主题 泻 染 等 ， oe 能 支持 文件 上 传 。 处 理 器 是 你 的 应 用 中 注解 

了 @controller 和 @RequestMapping 的 类 和 方法 ，Spring 为 处 理 器 器 方法 提供 了 极其 多 样 灵活 的 
配置 。Spring 3.0 以 后 提供 了 @controller 注解 机 制 、 @pathvariable 注解 以 及 一 些 其 他 的 特 
性 ， 你 可 以 使 用 它们 来 进行 RESTful web 站 点 和 应 用 的 开发 。 


“对 扩展 开放 ”是 Spring Web MVC 框 架 一 个 重要 的 设计 原则 ， 而 对 于 Spring 的 整个 完整 杠 
架 来 说 ， 其 设计 原 m) 则 是 “对 扩 展开 放 ， 对 修 改 闭合 ”。 


Spring Web MVC 核 心 类 库 中 的 一 些 方法 被 定义 为 final 方法 。 作 为 开发 人 员 ， 你 不 能 
窗 写 这 些 方法 以 定制 其 行为 。 当 然 ， 不 是 说 绝对 不 行 ， 但 请 记 住 这 条 原则 ， 绝 大 多 数 情 
况 下 不 是 好 的 实践 。 


关于 该 原则 的 详细 解释 ， 你 可 以 参考 Seth Ladd 等 人 所 著 的 “深入 解析 Spring Web MVC4 
Web Flow” 一 书 。 相 关 信 息 在 第 117 页 ，“ 设 计 初 探 (ALook At Design) "一 节 。 或 者 ， 你 
可 以 参考 : 


。 Bob Martin 所 写 的 “ 开 闭 原则 (The Open-Closed Principle) ” (PDF) 


你 无 法 增强 Spring MVC 中 的 final 方法 ， 比 


如 AbstractController. setSynchronize0nSession() 方 法 等 。 请 参 #10. 6.1 理 — 
一 节 ， 其 中 解释 了 AOP 代 理 的 相关 知识 ， 论 述 了 为 什么 你 不 能 对 Final 方法 进行 增强 。 


在 Spring Web MVC 中 ， 你 可 以 使 用 任何 对 象 来 作为 命令 对 象 或 表单 返回 对 象 ， 而 无 须 实现 一 
个 框架 相关 的 接口 或 基 类 。Spring 的 数据 绑 定 非常 灵活 : 比如 ， 它 会 把 数据 类 型 不 匹配 当成 可 
由 应 用 自行 处 理 的 运行 时 验证 错误 ， 而 非 系 统 错误 。 你 可 能 会 为 了 避免 非法 的 类 型 转换 在 表 
单 对 象 中 使 用 字符 串 来 存储 数据 ， 但 无 类 型 的 字符 串 无 法 描述 业务 数据 的 趴 正 含义 ， 
还 需要 把 它们 转换 成 对 应 的 业务 对 象 类 型 。 有 了 Spring 的 验证 机 制 ， 意 味 着 你 再 也 不 需 这 么 做 
了 ， 并 且 直 接 将 业务 对 象 绑 定 到 表单 对 象 上 通常 是 更 好 的 选择 。 


和 解析 也 是 设计 得 异常 灵活 。 控 制 器 一 般 负责 准备 一 个 map 模型 、 填 充 数据 、 

回 一 个 合适 的 视图 名 等 ， 同 时 它 也 可 以 直接 将 数据 写 到 响应 流 中 。 视 图 名 的 解析 高 度 oe ， 
支持 多 种 配置 ， 包 括 通过 文件 扩展 名 、 accept 内 容 头 、bean、 配 置 文件 等 的 配置 ， 甚 至 你 还 
可 以 自己 实现 一 个 视图 解析 器 ViewResolver 。 模 型 (MVC F 的 M ， model ) 其 实 是 一 

个 map 类 型 的 接口 ， 彻 底 地 把 数据 从 视图 技术 中 抽象 分 离 了 出 来 。 你 可 以 与 基于 模板 的 泻 染 
技术 直接 整合 ， 如 JSP、Velocity 和 Freemarker 等 ， 或 者 你 还 可 以 直接 生成 XML、JSON、 
Atom 以 及 其 他 多 种 类 型 的 内 容 。 map 模型 会 简单 地 被 转换 成 合适 的 格式 ， 比 如 JSP 的 请 求 属 
性 (attribute) ， 一 个 Velocity 模板 的 模型 等 


Spring Web MVC 框 架 简介 
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21.1.1 Spring Web MVC 49 #7 44 t 


Spring Web Flow 


Spring Web Flow (SWF) 意 在 成 为 web 应 用 中 的 页 面 流 (page flow) 管 理 中 最 好 的 解决 方 


ee 
xO 


SWF 在 Servlet 环 境 和 Portlet 环 境 下 集成 了 现 有 的 框架 ， 如 Spring MVC 和 JSF 等 。 如 果 你 
的 业务 流程 有 一 个 贯穿 始终 的 模型 ， 而 非 单 纯 分 立 的 请 求 ， 那 么 SWF 可 能 是 适合 你 的 解 
决 方案 A ° 


SWF 允 许 你 将 逻辑 上 的 页 面 流 抽取 成 独立 可 复 用 的 模块 ， 这 对 于 构建 一 个 web 应 用 的 多 
个 模块 是 有 益 的 。that guide the user through controlled navigations that drive business 
processes. 


关于 SWF 的 更 多 信息 ， 请 访问 Spring Web Flow’) € 


Spring 的 web 模 块 支持 许多 web 相 关 的 特性 





。 清晰 的 职责 分 制 器 ， 验 证 器 ， 命 令 对 象 ， 表 单 对 象 ， 模 型 对 
象 ，Dispatcherservlet ， 处 理 器 > 视图 解析 器 ， 等 等 许多 一 一 的 工作 ， 都 可 以 由 相 


应 的 对 象 来 完成 。 
o 强大 、 直 观 的 框架 和 应 Cs 。 这 种 配置 能 力 包 括 能 够 从 不 同 的 上 下 文中 进行 简 
单 的 引用 ， 比 如 在 web 控 制 器 中 引用 业务 对 象 、 验 证 器 等 。 
强大 的 适 配 能 力 、 eee © Spring MVC 支 持 你 定义 任意 的 控制 器 方法 签名 ， 
在 特定 的 场景 下 你 还 可 以 添加 适合 的 注解 (上 比 
如 @RequestParam ` @RequestHeader ` @PathVariable 等 ) 
© 可 复 用 的 业务 代码 ， 使 你 远离 重复 代码 。 hes oe 象 作为 命令 对 象 或 表 
单 对 象 ， 而 不 需 让 U E 提供 的 什么 
可 定制 的 数据 绑 定 和 验证 。 类 > Bik > Ae 
化 日 期 、 数 字 绑 定 等 会 被 保存 。 你 不 需要 再 在 表单 对 象 使 用 全 String 字 段 ， 然 后 再 手动 将 
它们 转换 成 业务 对 象 。 
可 定制 的 处 理 器 映射 和 视图 解 村。 处理 器 映射 和 视图 解析 策略 从 简单 的 基于 URL 配 置 ， 
到 精细 专用 的 解析 策略 ，Spring 全 都 支持 。 在 这 一 点 上 ，Spring 比 一 些 依 赖 于 特定 技术 的 
Web 框 架 要 更 加 灵活 。 
灵活 的 模型 传递 。Spring 使 用 一 个 名 称 / 值 对 的 Map 来 做 模型 ， 这 使 得 模型 很 容易 集成 、 
传递 给 任何 类 型 的 视图 技术 。 
可 定制 的 本 地 化 信息 、 时 区 和 主题 解析 。 支 持 用 /不 用 Spring 标 签 库 的 JSP 技 术 ， 支 持 
JSTL， 支 持 无 需 额外 配置 的 Velocity 模板 ， 等 等 。 
一 个 简单 但 功能 强大 的 JSP 标 签 库 ， 通 常 称 为 Spring 标签 库 ， 它 提供 了 诸如 数据 绑 定 、 主 
题 支持 等 一 些 特性 的 支持 。 这 些 定制 的 标签 为 标记 (markup) 你 的 代码 提供 了 最 大 程度 


的 灵活 性 。 关 于 标签 库 描述 符 〈descriptor) 的 更 多 信息 ， 请 参考 附录 第 42 章 Spring JSP 
。 一 个 Spring 2.0 开 始 引 入 的 JSP 表 单 标签 库 。 它 让 你 在 JSP 页 面 中 编写 表单 简单 许多 。 关 
于 标签 库 描 述 符 (descriptor) 的 更 多 信息 ， 请 参考 附录 第 43 章 Spring 表单 的 JSP 标 签 库 
。 新 增生 命 周期 仅 绑 定 到 当前 HTTP 请 求 或 HTTP 会 话 的 Bean 类 型 。 严 格 来 说 ， 这 不 是 
Spring MVC 自 身 的 特性 ， 而 是 Spring MVC 使 用 的 上 下 文 容器 webApplicationcontext 所 
提供 的 特性 。 这 些 bean 的 scope 在 6.5.4 请 求 、 会 话 及 全 局 会 话 sScope 一 节 有 详细 描述 。 


21.1.2 允许 其 他 MVC 实 现 


有 些 项 目 可 能 更 倾向 于 使 用 非 Spring 的 MVC 框 架 。 许 多 团队 希望 仍然 使 用 现 有 的 技术 栈 ， 比 
如 JSF 等 ， 这 样 他 们 掌握 的 技能 和 工具 依然 能 发 挥 作用 。 


如 果 你 确实 不 想 使 用 Spring 的 Web MVC， 但 又 希望 能 从 Spring 提供 的 一 些 解 决 方案 中 受益 ， 
那么 将 你 所 使 用 的 框 架 和 Spring 进行 集成 也 很 容易 。 只 需要 在 contextLoaderListener 中 局 动 
一 个 Spring 的 根 应 用 上 下 文 (root application context) ， 然 后 你 就 可 以 在 任何 action 对 象 中 通 
过 其 servietcontext 属性 【或 通过 Spring 对 应 的 helper 方 法 ) 取得 。 不 需要 任何 侵入 性 的 插 
件 ， 因 此 不 需要 复杂 的 集成 。 从 应 用 层 的 视角 来 看 ， 你 只 是 将 Spring 当成 依赖 库 使 用 ， 并 且 将 
它 的 根 应 用 上 下 文 实例 作为 应 用 进入 点 。 


即使 不 用 Spring 的 Web MVC 框 架 ， 你 配置 的 其 他 Spring 的 bean 和 服务 也 都 能 很 方便 地 取得 。 
在 这 种 场景 下 ，Spring 与 其 他 web 框 架 的 使 用 不 冲突 。Spring 只 是 在 许多 问题 上 提出 了 其 他 纯 
web MVC 框 架 未 曾 提 出 过 的 解决 方案 ， 比 如 bean 的 配置 、 数 据 存 取 、 事 务 处 理 等 ， 仅 此 而 
已 。 因 此 ， 如 果 你 只 是 想 使 用 Spring 的 一 部 分 特性 来 增强 你 的 应 用 ， 比 如 Spring 提 供 的 
JDBC/Hibernate 事 务 抽象 等 ， 那 么 你 可 以 将 Spring 作 为 一 个 中 间 层 和 /或 数据 存 取 层 来 使 用 。 


DispatcherServlet 


21.2 DispatcherServlet 


Spring MVC 框 架 ， 与 其 他 很 多 web 的 MVC 框 架 一 样 : 请 求 驱动 ; 所 有 设计 都 围绕 着 一 个 中 央 
Servlet 来 展开 ， 它 负责 把 所 有 请 求 分 发 到 控制 器 ; 同时 提供 其 他 web 应 用 开发 所 需要 的 功 

能 。 不 过 Spring 的 i eames 器 ， DispatcherServlet ， 能 做 的 比 这 更 多 。 它 与 Spring loC 容 器 
做 到 了 无 缝 集 成， 这 意味 着 ，Spring 提 供 的 任何 特性 ， 在 Spring MVC 中 你 都 可 以 使 用 。 


下 图 展示 了 Spring Web MVC 的 Dispatcherservlet 处 理 请 求 的 工作 流 。 熟 悉 设 计 模 式 的 朋友 
会 发 现 ， Dispatcherservlet 应 用 的 其 实 就 是 一 个 “前 端 控制 器 "的 设计 模式 (其 他 很 多 优秀 的 
Web 框 架 也 都 使 用 了 这 个 设计 模式 ) 。 





DispatcherServlet 其 实 就 是 个 servlet ( 它 继承 自 Httpservlet RA) ， 同 样 也 需要 在 你 
Web 应 用 的 web.xml 配置 文件 下 声明 。 你 需要 在 web.xml 文件 中 把 你 希 

Z DispatcherServlet 处 理 的 请 求 映 射 到 对 应 的 URL 上 去 。 这 就 是 标准 的 Java EE Servlet 配 
置 ; 下 面 的 代码 就 展示 了 对 Dispatcherservlet 和 路 径 映 射 的 声明 : 
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<web-app> 
<servlet> 
<servlet -name>example</servlet-name> 
<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class 


<load-on-startup>1</load-on-startup> 
</servlet> 


<servlet -mapping> 
<servlet -name>example</servlet-name> 
<url-pattern>/example/*</url-pattern> 
</servlet -mapping> 
</web-app> 


有 Egg 


In the preceding example, all requests starting with /example will be handled by the 
DispatcherServlet instance named example. In a Servlet 3.0+ environment, you also 
have the option of configuring the Servlet container programmatically. Below is the code 

based equivalent of the above web.xml example: 


在 上 面 的 例子 中 所 有 路 径 以 /example 开头 的 请 求 都 会 被 名 字 

为 example 的 DispatcherServlet 处 理 。 在 Servlet 3.0+ 的 环境 下 ， 你 还 可 以 用 编程 的 方式 配置 
Servlet 容 器 。 下 面 是 一 段 这 种 基于 代码 配置 的 例子 ， 它 与 上 面 定义 的 web.xml 配置 文件 是 等 
效 的 。 


public class MyWebApplicationInitializer implements WebApplicationInitializer { 


@Override 
public void onStartup(ServletContext container) { 
ServletRegistration.Dynamic registration = container.addServlet("dispatcher", 
new DispatcherServlet()); 
registration.setLoadOnStartup(1); 
registration.addMapping("/example/*"); 


WebApplicationInitializer 是 Spring MVC 提 供 的 一 个 接口 ， 它 会 查找 你 所 有 基于 代码 的 配 
置 ， 并 应 用 它们 来 初始 化 Servlet 3 版 本 以 上 的 web 容 器 。 它 有 一 个 抽象 的 实 

HL AbstractDispatcherServletInitializer ， 用 以 简化 Dispatcherservlet 的 注册 工作 : 你 只 需 
要 指定 其 servlet 映射 (mapping) 即 可 。 若 想 了 解 更 多 细节 ， 可 以 参考 基于 代码 的 Servlet 容 器 
初始 化 一 节 。 


上 面 只 是 配置 Spring Web MVC 的 第 一 步 ， 接 下 来 你 需要 配置 其 他 的 一 些 bean ( 除 
了 pispatcherservlet 以 外 的 其 他 bean) ， 它 们 也 会 被 Spring Web MVC 框 架 使 用 到 。 


在 6.15 应 用 上 下 文 ApplicationContext 的 其 他 作用 ) 一 节 中 我 们 聊 到 ，Spring 中 

的 ApplicationContext 实例 是 可 以 有 范围 (scope) 的 。 在 Spring MVC 中 ， 每 

AN DispatcherServlet 都 持 有 一 个 自己 的 上 下 文 对 象 WebApplicationContext ， 它 又 继承 了 根 
(root) WebApplicationContext 对 象 中 已 经 定义 的 所 有 bean 。 这 些 继承 的 bean 可 以 在 具体 的 

Servlet 实 例 中 被 重 载 ， 在 每 个 Servlet 实 例 中 你 也 可 以 定义 其 scope 下 的 新 bean。 


DispatcherServlet 


Servlet WebApplicationContext 


(containing controllers, view resolvers, 
and other web-related beans) 


| Controllers HandlerMapping 


Delegates if no bean found 


Root WebApplicationContext 


(containing middle-tier services, datasources, etc.) 


| serves 





DispatcherServlet 的 初始 化 过 程 中 ， Spring MVC 会 在 你 web 应 用 的 WEB-INF 目录 下 查找 一 个 
名 为 [servlet-name]-servlet.xml 的 配置 文件 ， 并 创建 其 中 所 定义 的 bean。 如 果 在 全 局 上 下 文中 
存在 相同 名 字 的 bean， 则 它们 将 被 新 定义 的 同名 bean 履 盖 。 


看 看 下 面 这 个 Dispatcherservlet 的 Servlet 配 置 (定义 于 Web.xml 文 件 中 ) 


<web-app> 
<servlet> 
<servlet -name>golfing</servlet -name> 
<servlet-class>org.springframework.web.servlet .DispatcherServlet</servlet-class 


<load-on-startup>1</load-on-startup> 
</servlet> 
<servlet -mapping> 
<servlet -name>golfing</servlet -name> 
<url-pattern>/golfing/*</url-pattern> 
</servlet -mapping> 
</web-app> 


4 a 


有 了 以 上 的 Servlet 配 置 文件 ， 你 还 需要 在 应 用 中 的 /WEB-INF/ 路 径 下 创建 一 个 golfing- 
servlet.xml 文件 ， 在 该 文件 中 定义 所 有 Spring MVC 相 关 的 组 件 (比如 bean 等 ) 。 你 可 以 通 
过 servlet 初始 化 参数 为 这 个 配置 文件 指定 其 他 的 路 径 (更 多 细节 请 参考 下 文 ) 。 


当 你 的 应 用 中 只 需要 一 个 DispatcherServlet 时 ， 只 配置 一 个 根 context 对 象 也 是 可 行 的 。 


DispatcherServlet 


(with empty contextConfigLocation) 


Servlet WebApplicationContext 


Delegates 


Root WebApplicationContext 


(containing all beans) 


| cos HandlerMapping 


Services Repositories 


要 配置 一 个 唯一 的 根 context 对 和 象 ， 可 以 通过 在 servlet 初始 化 参数 中 配置 一 个 空 的 
contextConfigLocation 来 做 到 ， 如 下 所 示 : 





<web-app> 
<context -param> 
<param-name>contextConfigLocation</param-name> 
<param-value>/WEB-INF/root-context.xml</param-value> 
</context -param> 
<servlet> 
<servlet -name>dispatcher</servlet -name> 


<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class 


<init-param> 
<param-name>contextConfigLocation</param-name> 
<param-value></param-value> 
</init -param> 
<load-on-startup>1</load-on-startup> 
</servlet> 
<servlet -mapping> 
<servlet -name>dispatcher</servlet -name> 
<url-pattern>/*</url-pattern> 
</servlet -mapping> 
<listener> 


<listener-class>org.springframework.web.context.ContextLoaderListener</listene 
r-class> 


</listener> 
</web -app> 


E SS 


WebApplicationContext 继承 自 applicationContext ， 它 提供 了 一 些 web 应 用 经 常 需要 用 到 的 
特性 。 它 与 普通 的 applicationcontext 不 同 的 地 方 在 于 ， 它 支持 主题 的 解析 ( 详 见 21.9 主题 
Themes 一 小 节 ) ， 并 且 知 道 它 关联 到 的 是 哪个 servlet ( 它 持 有 一 个 该 servletcontext 的 引 
用 ) ° WebApplicationContext WREE ServletContext + 2 如 果 需 要 获取 它 ， 你 可 以 通 

过 RequestContextUtils 工具 类 中 的 静态 方法 来 拿 到 这 个 web 应 用 的 上 下 

文 WebApplicationContext ° 


21.2.1 WebApplicationContext ¥ 44% 49 
bean & # 


Spring 的 DispatcherServlet 使 用 了 特殊 的 bean 来 处 理 请 求 、 浑 染 视 图 等 ， 这 些 特定 的 bean 有 是 
Spring MVC 框 架 的 一 部 分 。 如 果 你 想 指定 使 用 哪个 特定 的 bean， 你 可 以 在 web 应 用 上 下 

X WebApplicationcontext 中 简单 地 配置 它们 。 当 然 这 只 是 可 选 的 ，Spring MVC 维 护 了 一 个 默 
认 的 bean 列 表 ， 如 果 你 没有 进行 特别 的 配置 ， 框 架 将 会 使 用 默认 的 bean。 下 一 小 节 会 介绍 更 
多 的 细节 ， 这 里 ， 我 们 将 先 快速 地 看 一 下 ， Dispatcherservlet 都 依赖 于 哪些 特殊 的 bean 来 进 
行 它 的 初始 化 。 


bean 的 类 型 作用 


处 理 器 映射 。 它 会 根据 某 些 规则 将 进入 容器 的 请 求 映射 到 
具体 的 处 理 器 以 及 一 系列 前 处 理 器 和 后 处 理 器 〈 即 处 理 器 
HandlerMapping 拦截 器 ) 上 。 上 有 具体 的 规则 视 HandlerMapping 类 的 实现 不 同 
而 有 所 不 同 。 其 最 常用 的 一 个 实现 支持 你 在 控制 器 上 添加 
注解 ， 配 置 请 求 路 径 。 当 然 ， 也 存在 其 他 的 实现 。 


处 理 器 适配器 。 拿 到 请 求 所 对 应 的 处 理 器 后 ， 适 配器 将 负 

责 去 调用 该 处 理 器 ， 这 使 得 DispatcherServlet 无 需 关 心 具 
体 的 调用 细节 。 比 方 说 ， 要 调用 的 是 一 个 基于 注解 配置 的 

控制 器 ， 那 么 调用 前 还 需要 从 许多 注解 中 解析 出 一 些 相应 

的 信息 。 因 此 ， HandlerAdapter 的 主要 任务 就 是 

对 DispatcherServlet 屏蔽 这 些 具体 的 细节 © 


处 理 器 弄 常 解析 器 。 它 负责 将 捕获 的 异常 映射 到 不 同 的 视 
图 上 去 ， 此 外 还 支持 更 复杂 的 异常 处 理 代 码 。 

视图 解析 器 。 它 负责 将 一 个 代表 逻辑 视图 名 的 字符 囊 
(String) 映射 到 实际 的 视图 类 型 view 上 。 


地 区 解析 器 和 地 区 上 下 文 解析 器 。 它 们 负责 解析 客户 端 所 


L leR ili & > > ` = > > +] 坦 
E eee ， 地 区 信息 甚至 时 区 信息 ， 为 国际 化 的 视图 定制 提供 了 


主题 解析 器 。 它 负责 解析 你 web 应 用 中 可 用 的 主题 ， 比 


HandlerAdapter 


HandlerExceptionResolver 


ViewResolver 


WO 如 ， 提 供 一 些 个 性 化 定制 的 布局 等 。 
EEEE 解析 multi-part 的 传输 请 求 ， 比 如 支持 通过 HTML 表 单 进 行 


的 文件 上 传 等 。 


FlashMap 管 理 器 。 它 能 够 存储 并 取 回 两 次 请 求 之 间 
FlashMapManager 的 FlashMap 对 象 。 后 者 可 用 于 在 请 求 之 间 传 递 数据 ， 通 常 
是 在 请 求 重 定向 的 情境 下 使 用 。 


21.2.2 RU % DispatcherServletéc 4 


上 一 小 节 讲 到 ， pDispatcherServlet 维护 了 一 个 列表 ， 其 中 保存 了 其 所 依赖 的 所 有 bean 的 默认 
实现 。 这 个 列表 保存 在 包 org.springframework.web.servlet T 
的 DispatcherServlet.properties 文件 中 。 


些 特殊 的 bean 都 有 一 些 基 本 的 默认 行为 。 或 早 或 晚 ， 你 可 能 需要 对 它们 提供 的 一 些 默认 配 
进行 定制 。 比 如 说 ， 通常 你 需要 配置 InternalResourceViewResolver 类 提供 的 prefix 属 

性 ， 使 其 指向 视图 文件 所 在 的 目录 。 这 里 需要 理解 的 一 个 事情 是 ， 一 旦 你 在 web 应 用 上 下 
文 webApplicationcontext 中 配置 了 某 个 特殊 bean 以 后 (re 

如 InternalResourceViewResolver ) ， 实际 上 你 也 才 写 了 该 bean 的 默认 实现 。 比 方 说 ， 如 果 你 
配置 了 InternalResourceViewResolver ， 那 么 框架 就 不 会 再 使 用 bean viewResolver 的 默认 实 
现 。 


这 
置 


在 21.16 节 Spring MVC 的 配置 中 ， 我 们 介绍 了 其 他 配置 Spring MVC 的 方式 ， 比 如 通过 Java 编 
程 配置 或 者 通过 MVC XML 命名 空间 进行 配置 。 它 们 为 配置 一 个 Spring MVC 应 用 提供 了 简易 
的 开始 方式 ， 也 不 需要 你 对 框架 实现 细节 有 太 多 了 解 。 当 然 ， 无 论 你 选用 何 种 方式 开始 配 
置 ， 本 节 所 介绍 的 一 些 概念 都 是 基础 且 普 适 的 ， 它 们 对 你 后 续 的 学 习 都 应 有 所 助 益 。 


21.2.3 DispatcherServlet 的 处 理 流程 


配置 好 DispatcherServlet 以 后 ， 开 始 有 请 求 会 经 过 这 个 Dispatcherservlet 。 此 
时 ， DispatcherServlet 会 依照 以 下 的 次 序 对 请 求 进行 处 理 : 


e 首先 ， 搜 索 应 用 的 上 下 文 对 象 WebApplicationcontext 并 把 它 作为 一 个 属性 (attribute ) 
绑 定 到 该 请 求 上 ， 以 便 控 制 器 和 其 他 组 件 能 够 使 用 它 。 属 性 的 键 名 默认 
为 DispatcherServlet .WEB_APPLICATION_CONTEXT_ATTRIBUTE 

e 将 地 区 (locale) 解析 器 绑 定 到 请 求 上 ， 以 便 其 他 组 件 在 处 理 请 求 (RMA. ESR 
等 ) 时 可 以 获取 区 域 相关 的 信息 。 如 果 你 的 应 用 不 需要 解析 区 域 相关 的 信息 ， 忽 略 它 即 
可 

e 将 主题 (theme) 解析 器 绑 定 到 请 求 上 ， 以 便 其 他 组 件 (比如 视图 等 ) 能 够 了 解 要 泻 染 哪 
个 主题 文件 。 同 样 ， 如 果 你 不 需要 使 用 主题 相关 的 特性 ， 忽 略 它 即 可 

e 如 果 你 配置 了 multipart 文 件 处 理 器 ， 那 么 框架 将 查找 该 文件 是 不 是 multipart (分 为 多 
分 连续 上 传 ) 的 。 若 是 ， 则 将 该 请 求 包 装 成 一 个 MultipartHttpServletRequest 对 象 ， 以 
便 处 理 链 中 的 其 他 组 件 对 它 做 进一步 的 处 理 。 关 于 Spring 对 multipart 文 件 传 输 处 理 的 支 
持 ， 读 者 可 以 参考 21.10 Spring 的 multipart (文件 上 传 ) 支持 一 小 节 

© 为 该 请 求 查 找 一 个 合适 的 处 理 器 。 如 果 可 以 找到 对 应 的 处 理 器 ， 则 与 该 处 理 器 关联 的 整 
条 执行 链 (前 处 理 器 、 后 处 理 器 、 控 制 器 等 ) 都 会 被 执行 ， 以 完成 相应 模型 的 准备 或 视 
图 的 演 染 

e@ 如 果 处 理 器 返回 的 是 一 个 模型 (model) ， 那 么 框架 将 演 染 相应 的 视图 。 若 没有 返回 任何 
模型 (可 能 是 因为 前 后 的 处 理 器 出 于 某 些 原 因 拦 截 了 请 求 等 ， 比 如 ， 实 全 问题 ) >» ME 
架 不 会 泻 染 任何 视图 ， 此 时 认为 对 请 求 的 处 理 可 能 已 经 由 处 理 链 完成 了 


如 果 在 处 理 请 求 的 过 程 中 抛 出 了 常 ， 那 么 上 下 文 webApplicationcontext 对 象 中 所 定义 的 异 


常 处 理 器 将 会 负责 捕获 这 些 异常 。 通 过 配置 你 自己 的 异常 处 理 器 ， 你 可 以 定制 自己 处 理 异常 
的 方式 。 


Spring 的 Dispatcherservlet 也 允许 处 理 器 返回 一 个 Servlet API 规 范 中 定义 的 HIE HF PRAY lA] BR 
(last-modification-date) 值 。 决 定 请 求 最 后 修改 时 间 的 方式 很 直接 : Dispatcherservlet 会 
先 查 找 合适 的 处 理 器 映射 来 找到 请 求 对 应 的 处 理 器 ， 然 后 检测 它 是 否 实现 了 LastModified 接 
口 。 若 是 ， 则 调用 接口 的 long getLastModified(request) 方法 ， 并 将 该 返回 值 返回 给 客户 端 。 


你 可 以 定制 DispatcherServlet 的 配置 ， 具 体 的 做 法 ， 是 在 web.xml 文件 中 ，Servlet 的 声明 元 
素 上 添加 一 些 Servlet 的 初始 化 参数 (通过 init-param TH) 。 该 元 素 可 选 的 参数 列表 如 下 : 


contextClass 


contextConfigLocation 


namespace 


任意 实现 了 webapplicationcontext 接口 的 类 。 这 个 类 会 初始 
化 该 servlet 所 需要 用 到 的 上 下 文 对 象 。 上 默认 情况 下 ， 框 架 会 使 
用 一 个 xmlwebApplicationcontext xt Ro 


一 个 指定 了 上 下 文 配置 文件 路 径 的 字符 串 ， 该 值 会 被 传 入 

给 contextclass 所 指定 的 上 下 文 实例 对 象 。 该 字符 串 内 可 以 
包含 多 个 字符 囊 ， 字 符 串 之 间 以 逗号 分 隔 ， 以 此 支持 你 进行 多 
个 上 下 文 的 配置 。 在 多 个 上 下 文中 重复 定义 的 bean， 以 最 后 
加 载 的 bean 定 义 为 准 


WebApplicationContext 的 命名 空间 o 默认 是 [servJlet-name] - 
servlet 


21.3 42 #| (Controller) a & 


...Spring implements a controller in a very abstract way, which enables you to create a 
wide variety of controllers. 


空 制 器 作为 应 用 程序 逻辑 的 处 理 入 口 ， 它 会 负责 去 调用 你 已 经 实现 的 一 些 服务 


控制 器 会 接收 并 解析 用 户 的 请 求 ， 然 后 把 Re ， 由 视图 泻 染 出 页 面 最 
冬 呈 现 给 用 户 。Spring 对 控制 器 的 定义 非常 宽松 ， 这 意味 着 你 在 实现 控制 器 时 非常 自由 。 


(5 


通常 ， 一 个 


Spring 2.5 以 后 引入 了 基于 注解 的 编程 模型 ， 你 可 以 在 你 的 控制 器 实现 上 添 

加 @RequestMapping ` @RequestParam ` @ModelAttribute 等 注解 。 注 解 特性 既 支 持 基于 
Servlet 的 MVC， 也 可 支持 基于 Portlet 的 MVC。 通 过 此 种 方式 实现 的 控制 器 既 无 需 继 承 某 个 特 
定 的 基 类 ， 也 无 需 实 现 某 些 特定 的 接口 。 而 且 ， 它 通常 也 不 会 直接 依赖 于 Servlet 或 Portlet 的 
API 来 进行 编程 ， 不 过 你 仍然 可 以 很 容易 地 获取 Servlet 或 Portlet 相 关 的 变量 、 特 性 和 设施 等 。 


在 Spring 项 目的 官方 Github 上 你 可 以 找到 许多 项 目 ， 它 们 对 本 节 所 述 以 后 的 注解 支持 提 
供 了 进一步 增强 ， 比 如 说 MvcShowcase，MvcAjax，MvcBasic，PetClinic，PetCare 


AE 


村 o 


@Controller 
public class HelloworldController { 


@RequestMapping("/helloworld") 

public String helloworld(Model model) { 
model.addAttribute("message", "Hello World!"); 
return "helloWorld"; 


你 可 以 看 到 ， @controller 注解 和 @RequestMapping 注解 支持 多 样 的 方法 名 和 方法 签名 。 在 上 
面 这 个 例子 中 ， 方 法 接受 一 个 model 类 型 ed String 类 型 的 视图 名 。 但 
事实 上 ， 方 法 所 支持 的 参数 和 返回 值 有 非常 多 的 选择 ， 这 个 我 们 在 本 小 节 的 后 面部 分 会 提 
及 。 @controller 和 @RequestMapping 及 其 他 的 一 些 注解 ， 共 同 构成 了 Spring MVC 框 架 的 基本 
实现 。 本 节 将 详细 地 介绍 这 些 注 解 ， 以 及 它们 在 一 个 Servlet 环 境 下 最 党 被 使 用 到 的 一 些 场 


景 。 





21.3.1 使 用 @Controller 注 解 定 义 一 个 控制 器 


[Original] The @controller annotation indicates that a particular class serves the role 
of a controller. Spring does not require you to extend any controller base class or 
reference the Servlet API. However, you can still reference Servlet-specific features if 
you need to. 


@controller 注解 表明 了 一 个 类 是 作为 控制 器 的 角色 而 存在 的 。Spring 不 要 求 你 去 继承 任何 控 
制 器 基 类 ， 也 不 要 求 你 去 实现 Servlet 的 那 套 API。 当 然 ， 如 果 你 需要 的 话 也 可 以 去 使 用 任何 与 
Servlet 相 关 的 特性 和 设施 。 


[Original] The @controller annotation acts as a stereotype for the annotated class, 
indicating its role. The dispatcher scans such annotated classes for mapped methods 
and detects @RequestMapping annotations (see the next section). 


@controller 注解 可 以 认为 是 被 标注 类 的 原型 (stereotype) ， 表 明了 这 个 类 所 承担 的 角色 。 
分 派 器 ( DispatcherServlet ) 会 扫描 所 有 注解 了 @Controller ay 2. 检测 其 中 通 
过 @RequestMapping 注解 配置 的 方法 〈 详 见 下 一 小 节 ) © 


[Original] You can define annotated controller beans explicitly, using a standard Spring 
bean definition in the dispatcher’s context. However, the @controller stereotype also 
allows for autodetection, aligned with Spring general support for detecting component 
classes in the classpath and auto-registering bean definitions for them. 


当然 ， 你 也 可 以 不 使 用 @controller 注解 而 显 式 地 去 定义 被 注解 的 bean， 这 点 通过 标准 的 
Spring bean 的 定义 方式 ， 在 dispather 的 上 下 文 属性 下 配置 即 可 做 到 。 但 是 @controller 原型 
是 可 以 被 框架 自动 检测 的 ，Spring 支 持 classpath 路 径 下 组 件 类 的 自动 检测 ， 以 及 对 已 定义 
bean 的 自动 注册 。 


[Original] To enable autodetection of such annotated controllers, you add component 
scanning to your configuration. Use the spring-context schema as shown in the 
following XML snippet: 


你 需要 在 配置 中 加 入 组 件 扫 描 的 配置 代码 来 开启 框架 对 注解 控制 器 的 自动 检测 。 请 使 用 下 面 
XML 代 码 所 示 的 spring-context schema : 


使 用 @Controller 注 解 定义 一 个 控制 器 


<?xml version="1.0" encoding="UTF-8"?> 
<beans xmlns="http://www.springframework.org/schema/beans" 
xmlns:xsi="http: //www.w3.org/2001/XMLSchema-instance" 
xmlns:p="http://www.springframework.org/schema/p" 
xmLlns:context="http://www.springframework.org/schema/context" 
xSi:schemaLocation=" 
http://www. springframework.org/schema/beans 
http://www. springframework.org/schema/beans/spring-beans. xsd 
http://www. springframework.org/schema/context 
http://www. springframework.org/schema/context/spring-context.xsd"> 


<context:component-scan base-package="org.springframework.samples.petclinic.web"/> 
SUSS gon Soe 


</beans> 
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21.3.2 使 用 @RequestMapping 注 解 映 射 请 求 
路 径 


你 可 以 使 用 @RequestMapping 注解 来 将 请 求 URL， 如 /appointments 等 ， 映 射 到 整个 类 上 或 菜 
个 特定 的 处 理 器 方法 上 。 一 般 来 说 ， 类 级 别 的 注解 负责 将 一 个 特定 (或 符合 某 种 模式 ) 的 请 

求 路 径 映射 到 一 个 控制 器 上 ， 同 时 通过 方法 级 别 的 注解 来 细 化 映射 ， 即 根据 特定 的 HTTP 请 求 
方法 ("GET"POST" 方 法 等 ) 、HTTP 请 求 中 是 否 携带 特定 参数 等 条 件 ， 将 请 求 映射 到 匹配 的 
方法 上 。 


下 面 这 段 代码 示例 来 自 Petcare， 它 展示 了 在 Spring MVC 中 如 何在 控制 器 上 使 
用 @RequestMapping 注解 : 


@Controller 
@RequestMapping("/appointments" ) 
public class AppointmentsController { 


private final AppointmentBook appointmentBook; 


@Autowired 
public AppointmentsController(AppointmentBook appointmentBook) { 
this.appointmentBook = appointmentBook; 


@RequestMapping(method = RequestMethod.GET) 
public Map<String, Appointment> get() { 
return appointmentBook.getAppointmentsForToday(); 


@RequestMapping(path = "/{day}", method = RequestMethod.GET) 
public Map<String, Appointment> getForDay(@PathVariable @DateTimeFormat(iso=ISO.DA 
TE) Date day, Model model) { 
return appointmentBook.getAppointmentsForDay (day) ; 


@RequestMapping(path = "/new", method = RequestMethod.GET) 
public AppointmentForm getNewForm() { 
return new AppointmentForm(); 


@RequestMapping(method = RequestMethod.POST ) 
public String add(@Valid AppointmentForm appointment, BindingResult result) { 
if (result.hasErrors()) { 
return "appointments/new"; 


} 
appointmentBook.addAppointment(appointment); 
return "redirect: /appointments"; 


在 上 面 的 示例 中 ， 许 多 地 方 都 使 用 到 了 @RequestMapping 注解 。 第 一 次 使 用 点 是 作用 于 类 级 别 
的 ， 它 指示 了 所 有 /appointments 开头 的 路 径 都 会 被 映射 到 控制 器 下 。 get() 方法 上 

的 @RequestMapping 注解 对 请 求 路 径 进 行 了 进一步 细 化 : 它 仅 接受 GET 方 法 的 请 求 。 这 样 ， 一 
个 请 求 路 径 为 /appointments 、HTTP 方 法 为 GET 的 请 求 ， 将 会 最 终 进 入 到 这 个 方法 被 处 

理 。 add() 方法 也 做 了 类 似 的 细 化 ， 而 getNewForm() 方法 则 同时 注解 了 能 够 接受 的 请 求 的 
HTTP 方 法 和 路 径 。 这 种 情况 下 ， 一 个 路 径 为 appointments/new 、HTTP 方 法 为 GET 的 请 求 将 
会 被 这 个 方法 所 处 理 。 


getForDay() 方法 则 展示 了 使 用 @RequestMapping 注解 的 另 一 个 技巧 : URI 模 板 。 (关于 URI 模 
板 ， 请 见 下 小 节 ) 


类 级 别 的 @RequestMapping 注解 并 不 是 必须 的 。 不 配置 的 话 则 所 有 的 路 径 都 是 绝对 路 径 ， 而 非 
相对 路 径 。 以 下 的 代码 示例 来 自 PetClinic， 它 展示 了 一 个 具有 多 个 处 理 器 方法 的 控制 器 : 


@Controller 
public class ClinicController { 


private final Clinic clinic; 


@Autowired 
public ClinicController(Clinic clinic) { 
this.clinic = clinic; 


} 


@RequestMapping("/") 
public void welcomeHandler() { 


} 


@RequestMapping("/vets") 
public ModelMap vetsHandler() { 
return new ModelMap(this.clinic.getVets()); 


} 


以 上 代码 没有 指定 请 求 必 须 是 GET 方 法 还 是 PUT/POST 或 其 他 方法 ， @RequestMapping 注解 默 
认 会 映射 所 有 的 HTTP 请 求 方法 。 如 果 仅 想 接收 某 种 请 求 方法 ， 请 在 注解 中 指定 
之 @RequestMapping(method=GET ) 以 缩小 范围 。 


@Controller 和 面向 切面 (AOP) 代理 


有 时 ， 我 们 希望 在 运行 时 使 用 AOP 代 理 来 装饰 控制 器 ， 比 如 当 你 直接 在 控制 器 上 使 

用 @Transactional 注解 时 。 这 种 情况 下 ， 我 们 推荐 使 用 类 级 别 (在 控制 器 上 使 用 ) 的 代理 方 
式 。 这 一 般 是 代理 控制 器 的 默认 做 法 。 如 果 控 制 器 必须 实现 一 些 接 口 ， 而 该 接口 又 不 支持 
Spring Context 的 回调 (比如 InitializingBean ，*Aware 等 接口 ) ， 那 要 配置 类 级 别 的 代理 就 
必须 手动 配置 了 。 比 如 ， 原 来 的 配置 文件 <tx:annotation-driven/> 需要 显 式 配置 


为 <tx:annotation-driven proxy-target-class="true"/> ° 


Spring MVC 3.1 F? #122 %44#@RequestMapping 的 


一 些 类 


They are recommended for use and even required to take advantage of new features in 
Spring MVC 3.1 and going forward. 


使 用 @RequestMapping 注 解 映射 请 求 路 径 


Spring 3.1 中 新 增 了 一 组 类 用 以 增强 @RequestMapping ， 分 别 

是 RequestMappingHandlerMapping 和 RequestMappingHandlerAdapter 。 我 们 推荐 你 用 一 用 。 有 
部 分 Spring MVC 3.1 之 后 新 增 的 特性 ， 这 两 个 注解 甚至 是 必须 的 。 在 MVC 命 名 空间 和 MVC 

Java 编 程 配 置 方 式 下 ， 这 组 类 及 其 新 特性 默认 是 开启 的 。 但 若 你 使 用 其 他 配置 方式 ， 则 该 特 
性 必须 手动 配置 才能 使 用 。 本 小 节 将 简要 介绍 一 下 ， 新 类 相 比 之 前 的 一 些 重要 变化 。 


在 Spring 3.1 之 前 ， 框 架 会 在 两 个 不 同 的 阶段 分 别 检查 类 级 别 和 方法 级 别 的 请 求 映射 一 首 
先 ， DefaultAnnotationHanlderMapping 会 先 在 类 级 别 上 选 中 一 个 控制 器 ， 然 后 再 通 


过 AnnotationMethodHandlerAdapter 定位 到 具体 要 调用 的 方法 。 


[Original] With the new support classes in Spring 3.1, the 

RequestMappingHandlerMapping is the only place where a decision is made about which 
method should process the request. Think of controller methods as a collection of 
unique endpoints with mappings for each method derived from type and method-level 


@RequestMapping information. 


现在 有 了 Spring 3.1 后 引入 的 这 组 新 类 ， RequestMappingHandlerMapping 成 为 了 这 两 个 决策 实 
际 发 生 的 唯一 一 个 地 方 。 你 可 以 把 控制 器 中 的 一 系列 处 理 方法 当成 是 一 系列 独立 的 服务 节 
点 ， 每 个 从 类 级 别 和 方法 级 别 的 @RequestMapping 注解 中 获取 到 足够 请 求 1 路 径 映射 信息 。 


[Original] This enables some new possibilities. For once a HandlerInterceptor ora 
HandlerExceptionResolver Can now expect the Object-based handler to be a 
HandlerMethod , which allows them to examine the exact method, its parameters and 

associated annotations. The processing for a URL no longer needs to be split across 


different controllers. 


这 种 新 的 处 理 方式 带 来 了 新 的 可 能 性 。 之 前 


的 HandlerInterceptor 或 HandlerExceptionResolver 现在 可 以 确定 拿 到 的 这 个 处 理 器 肯定 是 一 
个 HandlerMethod 类 型 ， 因 此 它 能 够 精确 地 了 解 这 个 方法 的 所 有 信息 ， 包 括 它 的 参数 、 应 用 于 


其 上 的 注解 等 。 这 样 ， 内 部 对 于 一 个 URL 的 处 理 流程 再 也 不 需要 分 隔 到 不 同 的 控制 器 里 面 去 
执行 了 。 


[Original] There are also several things no longer possible: [Original] Select a controller 
first with a SimpleUrlHandlerMapping Of BeanNameUrlHandlerMapping and then narrow the 
method based on @RequestMapping annotations. [Original] Rely on method names as a 
fall-back mechanism to disambiguate between two @RequestMapping methods that don’t 
have an explicit path mapping URL path but otherwise match equally, e.g. by HTTP 
method. In the new support classes @RequestMapping methods have to be mapped 
uniquely. [Original] * Have a single default method (without an explicit path mapping) 
with which requests are processed if no other controller method matches more 
concretely. In the new support classes if a matching method is not found a 404 error is 


raised. 


同时 ， 也 有 其 他 的 一 些 变化 ， 比 如 有 些 事情 就 没 法 这 么 玩 儿 了 : 
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e 先 通 过 SimpleUrlHandlerMapping 或 BeanNameUr lHandlerMapping 来 拿 到 负 责 处 理 请 求 的 控 
制 器 ， 然 后 通过 @RequestMapping 注解 配置 的 信息 来 定位 到 具体 的 处 理 方法 ; 

© 依靠 方法 名 称 来 作为 选择 处 理 方法 的 标准 。 比 如 说 ， 两 个 注解 了 @RequestMapping 的 方法 
除了 方法 名 称 拥 有 完全 相同 的 URL 映 射 和 和 HTTP 请求 方法 。 在 新 版 本 
下 ， @RequestMapping 注解 的 方法 必须 具有 唯一 的 请 求 映 射 ; 

。 定义 一 个 默认 方法 〈 即 没有 声明 路 径 映射 ) ， 在 请 求 路 径 无 法 被 映射 到 控制 器 下 更 精确 
的 方法 上 去 时 ， 为 该 请 求 提供 默认 处 理 。 在 新 版 本 中 ， 如 果 无 法 为 一 个 请 求 找到 合适 的 
处 理 方法 ， 那 么 一 个 404 错 误 将 被 抛 出 ; 


[Original] The above features are still supported with the existing support classes. 
However to take advantage of new Spring MVC 3.1 features you'll need to use the new 
support classes. 


如 果 使 用 原来 的 类 ， 以 上 的 功能 还 是 可 以 做 到 。 但 是 ， 如 果 要 享受 Spring MVC 3.1 版 本 带 来 
的 方便 特性 ， 你 就 需要 去 使 用 新 的 类 。 


[Original] ## URI Template Patterns 


URI 模 板 


[Original] URI templates can be used for convenient access to selected parts of a URL 
ina @RequestMapping method. 


URI 模 板 可 以 为 快速 访问 @RequestMapping 中 指定 的 URL 的 一 个 特定 的 部 分 提供 很 大 的 便利 。 


[Original] AURI Template is a URI-like string, containing one or more variable names. 
When you substitute values for these variables, the template becomes a URI. The 
proposed RFC for URI Templates defines how a URI is parameterized. For example, 
the URI Template http://www.example.com/users/{userId} Contains the variable userld. 
Assigning the value fred to the variable yields http://ww.example.com/users/fred . 


URI 模 板 是 一 个 类 似 于 URI 的 字符 串 ， 只 不 过 其 中 包含 了 一 个 或 多 个 的 变量 名 。 当 你 使 用 实际 
的 值 去 填充 这 些 变 量 名 的 时 候 ， 模 板 就 退化 成 了 一 个 URI。 在 URI 模 板 的 RFC 提 议 中 定义 了 一 
个 URI 是 如 何 进行 参数 化 的 。 比 如 说 ， 一 个 这 个 URI 模 

板 http://www.example.com/users/{userId} 就 包含 了 一 个 变量 名 userldq。 将 值 fed 赋 给 这 个 变 


量 名 后 ， 它 就 变 成 了 一 个 URI : http://www.example.com/users/fred ° 


[Original] In Spring MVC you can use the @Pathvariable annotation on a method 
argument to bind it to the value of a URI template variable: 


在 Spring MVC 中 你 可 以 在 方法 参数 上 使 用 @Pathvariable 注解 ， 将 其 与 URI 模 板 中 的 参数 绑 定 
起 来 : 


使 用 @RequestMapping 注 解 映射 请 求 路 径 


@RequestMapping(path="/owners/{ownerId}", method=RequestMethod.GET ) 
public String findOwner(@PathVariable String ownerId, Model model) { 
Owner owner = ownerService.findOwner (ownerId); 
model.addAttribute("owner", owner); 
return "displayOwner"; 


[Original] The URI Template " /owners/{owner1d} " specifies the variable name 

ownerId . When the controller handles this request, the value of ownertd is set to the 
value found in the appropriate part of the URI. For example, when a request comes in 
for /owners/fred , the value of ownerId iS fred 


URI 模 板 " /owners/{owner1d} "指定 了 一 个 变量 ， 名 为 ownerId 。 当 控制 器 处 理 这 个 请 求 的 时 
候 ， ownerId 的 值 就 会 被 URI 模 板 中 对 应 部 分 的 值 所 填充 。 比 如 说 ， 如 果 请 求 的 URI 
是 /owners/fred ， 此 时 变量 ownerId 的 值 就 是 fred .` 


为 了 处 理 @pathvariables 注解 ，Spring MVC 必 须 通 过 变量 名 来 找到 URI 模 板 中 相对 应 的 
变量 。 你 可 以 在 注解 中 直接 声明 : 


@RequestMapping(path="/owners/{ownerId}}", method=RequestMethod.GET) 
public String findOwner(@PathVariable("ownerId") String theOwner, Model model) { 
// 具体 的 方法 代码 .… 


或 者 ， 如 果 URI 模 板 中 的 变量 名 与 方法 的 参数 名 是 相同 的 ， 则 你 可 以 不 必 再 指定 一 次 。 只 
要 你 在 编译 的 时 候 留 下 debug 信 息 ，Spring MVC 就 可 以 自动 匹配 URL 模 板 中 与 方法 参数 
名 相同 的 变量 名 。 


@RequestMapping(path="/owners/{ownerId}", method=RequestMethod. GET) 
public String findOwner(@PathVariable String ownerId, Model model) { 
// 具体 的 方法 代码 .… 


[Original] A method can have any number of @Pathvariable annotations: 


一 个 方法 可 以 拥有 任意 数量 的 @Pathvariable 注解 : 


@RequestMapping(path="/owners/{ownerId}/pets/{petId}", method=RequestMethod.GET ) 
public String findPet(@PathVariable String ownerId, @PathVariable String petId, Model 
model) { 

Owner owner = ownerService.findOwner (ownerId); 

Pet pet = owner.getPet(petId); 

model.addAttribute("pet", pet); 

return "displayPet"; 
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使 用 @RequestMapping 注 解 映射 请 求 路 径 


[Original] When a @Pathvariable annotation is used on a Map<String, String> 
argument, the map is populated with all URI template variables. 


4 @Pathvariable 注解 被 应 用 于 map<String, String> 类 型 的 参数 上 时 ， 框 架 会 使 用 所 有 URI 模 
板 变 量 来 填充 这 个 map。 


[Originall AURItemplate can be assembled from type and path level 


@RequestMapping annotations. As a result the findPet() method can be invoked 
with a URL such as /owners/42/pets/21 . 


URI 模 板 可 以 从 类 级 别 和 方法 级 别 的 @RequestMapping 注解 获取 数据 。 因 此 ， 像 这 样 
的 findPet() 方法 可 以 被 类 似 于 /owners/42/pets/21 这 样 的 URL 路 由 并 调用 到 : 


_@Controller_ 
@RequestMapping("/owners/{ownerId}") 
public class RelativePathUriTemplateController { 


@RequestMapping("/pets/{petid}") 


public void findPet(_@PathVariable_ String ownerId, _@PathVariable_ String petId, 
Model model) { 


// 方法 实现 体 这 里 忽略 


} 


[Original] A @Pathvariable argument can be of any simple type such as int, long, Date, 
etc. Spring automatically converts to the appropriate type or throws a 
TypeMismatchException if it fails to do so. You can also register support for parsing 
additional data types. See the section called "Method Parameters And Type 
Conversion" and the section called "Customizing WebDataBinder initialization". 


@PathVariable 可 以 被 应 用 于 所 有 简单 类 型 HARE > retint ` long` Date X# © Spring 
会 自动 地 帮 你 把 参数 转化 成 合适 的 类 型 ， 如 果 转 换 失 败 ， 就 抛 出 一 

个 TypeMismatchException 。 如 果 你 需要 处 理 其 他 数据 类 型 的 转换 ， 也 可 以 注册 自己 的 类 。 若 
需要 更 详细 的 信息 可 以 参考 “方法 参数 与 类 型 转换 "一 节 和 "定制 WebDataBinder 初 始 化 过 程 "一 


ae 
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带 正 则 表达 式 的 URI 模 板 


[Original] Sometimes you need more precision in defining URI template variables. 


Consider the URL "/spring-web/spring-web-3.0.5.jar" . How do you break it down into 
multiple parts? 
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使 用 @RequestMapping 注 解 映射 请 求 路 径 


有 时 候 你 可 能 需要 更 准确 地 描述 一 个 URI 模 板 的 变量 ， 比 如 说 这 个 URL : "/spring- 
web/spring-web-3.0.5.jar ° 你 要 怎么 把 它 分 解 成 几 个 有 意义 的 部 分 呢 ? 


[Original] The @RequestMapping annotation supports the use of regular expressions in 
URI template variables. The syntax is {varName:regex} where the first part defines the 
variable name and the second - the regular expression.For example: 


@RequestMapping 注解 支持 你 在 URI 模 板 变量 中 使 用 正则 表达 式 。 语 法 是 {varName:regex} ， 
其 中 第 一 部 分 定义 了 变量 名 ， 第 二 部 分 就 是 你 所 要 应 用 的 正则 表达 式 。 比 如 下 面 的 代码 样 
例 : 


@RequestMapping("/spring-web/{symbolicName: [a-z-]+}-{version: \\d\\.\\d\\.\\d}{extensio 
n:\\. [a-z]+}") 
public void handle(@PathVariable String version, @PathVariable String extension) { 
// 代码 部 分 省 略 ,,， 


Path Patterns (不 好 翻 ， 容 易 掉 韵味 ) 


[Original] In addition to URI templates, the @Requestmapping annotation also supports 
Ant-style path patterns (for example, /myPath/*.do ). A combination of URI template 
variables and Ant-style globs is also supported (e.g. /owners/*/pets/{petId} ). 


除了 URI 模 板 外 ， @RequestMapping 注解 还 支持 Ant 风 格 的 路 径 模式 〈 如 ymypath/*.do 等 ) 。 
不 仅 如 此 ， 还 可 以 把 URI 模 板 变 量 和 Ant 风 格 的 glob 组 合 起 来 使 用 《〈 比 
如 /owners/*/pets/{petid} 这 样 的 用 法 等 ) © 


路 径 样 式 的 匹配 (Path Pattern Comparison) 


[Original] When a URL matches multiple patterns, a sort is used to find the most 
specific match. 


当 一 个 URL 同 时 匹配 多 个 模板 (pattern) 时 ， 我 们 将 需要 一 个 算法 来 决定 其 中 最 匹配 的 一 
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[Original] A pattern with a lower count of URI variables and wild cards is considered 
more specific. For example /hotels/{hotel}/* has 1 URI variable and 1 wild card and 
is considered more specific than /hotels/{hotel}/** which as 1 URI variable and 2 
wild cards. 


QA 
UT 


} @RequestMapping 注 解 映射 请 求 路 径 


URI 模 板 变 量 的 数目 和 通配符 数量 的 总 和 最 少 的 那个 路 径 模 板 更 准确 。 举 个 例 
F > /hotels/{hotel}/* 这 个 路 径 拥 有 一 个 URI 变 量 和 一 个 通配符 ， 而 /hotels/{hotel}/** 这 
个 路 径 则 拥有 一 个 URI 变 量 和 两 个 通配符 ， 因 此 ， 我 们 认为 前 者 是 更 准确 的 路 径 模 板 。 


[Original] If two patterns have the same count, the one that is longer is considered more 
specific. For example /foo/bar* is longer and considered more specific than /foo/* . 


如 果 两 个 模板 的 URI 模 板 数量 和 通配符 数量 总 和 一 致 ， 则 路 径 更 长 的 那个 模板 更 准确 。 举 个 例 
F > /foo/bar* 就 被 认为 比 /foo/* 更 准确 ， 因 为 前 者 的 路 径 更 长 。 


[Original] When two patterns have the same count and length, the pattern with fewer 


wild cards is considered more specific. For example /hotels/{hotel} is more specific 
than /hotels/* . 


如 果 两 个 模板 的 数量 和 长 度 均 一 致 ， 则 那个 具有 更 少 通配符 的 模板 是 更 加 准确 的 。 比 
如 ， /hotels/{hotel} 就 比 /hotels/* 更 精确 。 


[Original] There are also some additional special rules: 
除 此 之 外 ， 还 有 一 些 其 他 的 规则 : 


[Original] The default mapping pattern /* is less specific than any other pattern. 
For example /api/{a}/{b}/{c}’ is more specific. 


[Original] A prefix pattern such as ‘/public/* is less specific than any other pattern 
that doesn't contain double wildcards. For example /public/path3/{a}/{b}/{c} is more 
specific. 


© 默认 的 通 配 模式 /** 比 其 他 所 有 的 模式 都 更 “不 准确 ”。 比 方 说 ， = /api/{a}/{b}/{c} 就 比 
默认 的 通 配 模 式 /** 要 更 准确 

o 前 级 通 配 (比如 /public/** ) 被 认为 比 其 他 任何 不 包括 双 通 配 符 的 模式 更 不 准确 。 比 如 
说 ， /public/path3/{a}/{b}/{c} 就 比 /public/** 更 准确 


[Original] For the full details see antPatterncomparator in AntPathMatcher . Note that 
the PathMatcher can be customized (see Section 21.16.11, "Path Matching" in the 
section on configuring Spring MVC). 


更 多 的 细节 了 请 参考 这 两 个 R : AntPatternComparator 和 AntPathMatcher ° 值得 一 提 的 是 
PathMatcher 类 是 可 以 配置 的 〈《 见 "配置 Spring MVC” 一 节 中 的 21.16.11 路 径 的 匹配 一 节 ) 。 


带 占 位 符 的 路 径 模 式 (path patterns ) 
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[Original] Patterns in @RequestMapping annotations support ${...} placeholders against 
local properties and/or system properties and environment variables. This may be 
useful in cases where the path a controller is mapped to may need to be customized 
through configuration. For more information on placeholders, see the javadocs of the 


PropertyPlaceholderConfigurer class. 


@RequestMapping 注解 支持 在 路 径 中 使 用 占 位 符 ， 以 取得 一 些 本 地 配置 、 系 统 配 置 、 环 境 变量 
等 。 这 个 特性 有 时 很 有 用 ， 比 如 说 控制 器 的 映射 路 径 需 要 通过 配置 来 定制 的 场景 。 如 果 想 了 
解 更 多 关于 占 位 符 的 信息 ， 可 以 参考 propertyPlaceholderconfigurer 这 个 类 的 文档 。 


Suffix Pattern Matching 


后 级 模式 匹配 


[Original] By default Spring MVC performs ".*" suffix pattern matching so that a 
controller mapped to /person is also implicitly mapped to /person.* . This makes it 
easy to request different representations of a resource through the URL path (e.g. 


/person.pdf , /person.xml ). 


Spring MVC 默 认 采 用 ".*" 的 后 级 模式 匹配 来 进行 路 径 匹 配 ， 因 此 ， 一 个 映射 到 /person 路 
径 的 控制 器 也 会 隐 式 地 被 映射 到 /person.* 。 这 使 得 通过 URL 来 请 求 同 一 资源 文件 的 不 同 格 
式 变 得 更 简单 (比如 /person.pdf ， /person.xml ) ° 


[Original] Suffix pattern matching can be turned off or restricted to a set of path 
extensions explicitly registered for content negotiation purposes. This is generally 
recommended to minimize ambiguity with common request mappings such as 

/person/{id} where a dot might not represent a file extension, e.g. 

/person/joe@email.com VS /person/joe@email.com.json) . Furthermore as explained in 
the note below suffix pattern matching as well as content negotiation may be used in 
some circumstances to attempt malicious attacks and there are good reasons to restrict 
them meaningfully. 


你 可 以 关闭 默认 的 后 级 模式 匹配 ， 或 者 显 式 地 将 路 径 后 组 限定 到 一 些 特定 格式 上 for content 
negotiation purpose。 我 们 推荐 这 样 做 ， 这 样 可 以 减少 映射 请 求 时 可 以 带 来 的 一 些 二 义 性 ， 比 
如 请 求 以 下 路 径 /person/{id} 时 ， 路 径 中 的 点 号 后 面 带 的 可 能 不 是 描述 内 容 格 式 ， 比 

如 /person/joe@email.com VS /person/joe@email.com.json 。 而 且 正 如 下 面 马 上 要 提 到 的 ， 后 
组 模式 通 配 以 及 内 容 协商 有 时 可 能 会 被 黑客 用 来 进行 攻击 ， 因 此 ， 对 后 组 通 配 进行 有 意义 的 
限定 是 有 好 处 的 。 
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使 用 @RequestMapping 注 解 映 射 请 求 路 径 


[Original] See Section 21.16.11, "Path Matching" for suffix pattern matching 
configuration and also Section 21.16.6, "Content Negotiation" for content negotiation 


configuration. 


关于 后 级 模式 匹配 的 配置 问题 ， 可 以 参考 第 21.16.11 小 节 "路径 匹配 " ; 关于 内 容 协商 的 配置 问 
题 ， 可 以 参考 第 21.16.6 小 节 "内 容 协商 "的 内 容 。 


后 级 模式 匹配 与 RFD 


[Original] Reflected file download (RFD) attack was first described in a paper by 
Trustwave in 2014. The attack is similar to XSS in that it relies on input (e.g. query 
parameter, URI variable) being reflected in the response. However instead of inserting 
JavaScript into HTML, an RFD attack relies on the browser switching to perform a 
download and treating the response as an executable script if double-clicked based on 


the file extension (e.g. .bat, .cmd). 


RFD(Reflected file download) 攻 击 最 先是 2014 年 在 Trustwave 的 一 篇 论文 中 被 提出 的 。 它 与 

XSS 攻 击 有 些 相似 ， 因 为 这 种 攻击 方式 也 依赖 于 某 些 特征 ， 即 需要 你 的 输入 〈 比 如 查询 参 

数 ，URI 变 量 等 ) 等 也 在 输出 (response) 中 以 某 种 形式 出 现 。 不 同 的 是 ，RFD 攻 击 并 不 是 通 

过 在 HTML 中 写 入 JavaScript 代 码 进 行 ， 而 是 依赖 于 浏览 器 来 跳 转 到 下 载 页 面 ， 并 把 特定 格式 
(比如 .bat，.cmd 等 ) 的 response 当 成 是 可 执行 脚本 ， 双 击 它 就 会 执行 。 


[Original] In Spring MVC @ResponseBody and ResponseEntity methods are at risk 
because they can render different content types which clients can request including via 
URL path extensions. Note however that neither disabling suffix pattern matching nor 
disabling the use of path extensions for content negotiation purposes alone are 
effective at preventing RFD attacks. 


Spring MVC 的 @ResponseBody 和 ResponseEntity 方法 是 有 风险 的 ， 因 为 它们 会 根据 客户 的 请 
求 一 包括 URL 的 路 径 后 级 ， 来 泻 染 不 同 的 内 容 类 型 。 因 此 ， 茜 用 后 组 模式 匹配 或 者 禁用 仅 
为 内 容 协 商 开 居 的 路 径 文件 后 组 名 携带 ， 都 是 防范 RFD 攻 击 的 有 效 方式 。 





[Original] For comprehensive protection against RFD, prior to rendering the response 
body Spring MVC adds a Content-Disposition: inline; filename=f.txt header to 
suggest a fixed and safe download file filename. This is done only if the URL path 
contains a file extension that is neither whitelisted nor explicitly registered for content 
negotiation purposes. However it may potentially have side effects when URLs are 


typed directly into a browser. 


若 要 开启 对 RFD 更 高 级 的 保护 模式 ， 可 以 在 Spring MVC 浑 娄 开 始 请 求 正 文 之 前 ， 在 请 求 头 中 
增加 一 行 配置 Content-Disposition:inline;filename=f.txt ， 指 定 固定 的 下 载 文 件 的 文件 名 。 
这 仅 在 URL 路 径 中 包含 了 一 个 文件 符合 以 下 特征 的 拓展 名 时 适用 : 该 扩展 名 既 不 在 信任 列表 
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使 用 @RequestMapping 注 解 映 射 请 求 路 径 


( 白 名 单 ) 中 ， E E EA E 。 并 且 这 种 做 法 还 可 以 有 一 些 副 作 
用 ， 比 如 ， 当 URL 是 通过 浏览 器 手动 输入 的 时 候 。 


[Original] Many common path extensions are whitelisted by default. Furthermore REST 
API calls are typically not meant to be used as URLs directly in browsers. Nevertheless 
applications that use custom HttpMessageConverter implementations can explicitly 
register file extensions for content negotiation and the Content-Disposition header will 
not be added for such extensions. See Section 21.16.6, "Content Negotiation”. 


常用 的 路 径 文件 后 缀 上 默认 是 被 信任 的 。 另 外 ，REST 的 API 一 般 是 不 应 该 直接 用 做 URL 
o 不过， 你 可 以 自己 定制 HttpMessageConverter 的 实现 ， 然 后 显 式 地 注册 用 于 内 容 协商 的 文 
件 类 型 ， 这 种 情形 下 Content-Disposition 头 将 不 会 被 加 入 到 请 求 头 中 。 详 见 第 21.16.6 节 中 “内 
容 协商 "的 内 容 。 


[Original] This was originally introduced as part of work for CVE-2015-5211. Below are 


additional recommendations from the report: 


e Encode rather than escape JSON responses. This is also an OWASP XSS 
recommendation. For an example of how to do that with Spring see spring-jackson- 
owasp. 

e Configure suffix pattern matching to be turned off or restricted to explicitly 
registered suffixes only. 

e Configure content negotiation with the properties "useJaf" and 
"ignoreUnknownPathExtensions" set to false which would result in a 406 response 
for URLs with unknown extensions. Note however that this may not be an option if 
URLs are naturally expected to have a dot towards the end. 

e Add x-Content-Type-Options: nosniff header to responses. Spring Security 4 


does this by default. 
感觉 这 节 的 翻译 质量 还 有 限 ， 需 要 继续 了 解 XSS 攻 击 和 RFD 攻 击 的 细节 再 翻 。 


矩阵 变量 


[Original] The URI specification RFC 3986 defines the possibility of including name- 
value pairs within path segments. There is no specific term used in the spec. The 
general "URI path parameters" could be applied although the more unique "Matrix 
URIs", originating from an old post by Tim Berners-Lee, is also frequently used and 
fairly well Known. Within Spring MVC these are referred to as matrix variables. 


原来 的 URI 规 范 RFC 3986 中 允许 在 路 径 段 落 中 携带 键 值 对 ， 但 规范 没有 明确 给 这 样 的 键 值 对 
定义 术语 。 有 人 叫 “URI 路 径 参 数 "， 也 有 叫 “ 和 矩阵 JRI”" 的 。 后 者 是 Tim Berners-Lee 首 先 在 其 博 
客 中 提 到 的 术语 ， 被 使 用 得 要 更 加 频繁 一 些 ， 知 名 度 也 更 高 些 。 而 在 Spring MVC F > RMA 
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使 用 @RequestMapping 注 解 映射 请 求 路 径 


这 样 的 键 值 对 为 矩阵 变量 。 


[Original] Matrix variables can appear in any path segment, each matrix variable 
separated with a ";" (semicolon). For example: "/cars;color=red;year=2012" . Multiple 


values may be either "," (comma) separated "color=red, green, blue" or the variable 
name may be repeated "color=red;color=green;color=blue" . 


FETE RS TV EE RARE F ROL EMER ESZ MEATS VF o te RHA) 
URI: "/cars;color=red;year=2012" 。 多 个 值 可 以 用 去 号 隔 开 "color=red, green, blue" ， 或 者 


重复 变量 名 多 次 "color=red;color=green;color=blue" ° 


[Original] If a URL is expected to contain matrix variables, the request mapping pattern 
must represent them with a URI template. This ensures the request can be matched 
correctly regardless of whether matrix variables are present or not and in what order 
they are provided. 


如 果 一 个 URL 有 可 能 需要 包含 矩阵 变量 ， 那 么 在 请 求 路 径 的 映射 配置 上 就 需要 使 用 URI 模 板 来 
体现 这 一 点 。 这 样 才 能 确保 请 求 可 以 被 正确 地 上 映射， 而 不 管 矩阵 变量 在 URI 中 是 否 出 现 、 出 现 
的 次 序 是 怎样 等 。 


[Original] Below is an example of extracting the matrix variable "q": 


Thk- lt > Rar T R11 4047 VEE RS PRPS] E Eqa : 
// GET /pets/42; q=11; r=22 


@RequestMapping(path = "/pets/{petId}", method = RequestMethod.GET ) 
public void findPet(@PathVariable String petId, @MatrixVariable int q) { 


// petId == 42 
// q == 11 


[Original] Since all path segments may contain matrix variables, in some cases you 
need to be more specific to identify where the variable is expected to be: 


由 于 任意 路 径 段 落 中 都 可 以 含有 和 矩阵 变量 ， 在 某 些 场 景 下 ， 你 需要 用 更 精确 的 信息 来 指定 一 
个 矩阵 变量 的 位 置 : 
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使 用 @RequestMapping 注 解 映射 请 求 路 径 


// GET /owners/42;q=11/pets/21;q=22 


@RequestMapping(path = "/owners/{ownerId}/pets/{petId}", method = RequestMethod.GET) 
public void findPet( 

@MatrixVariable(name="q", pathVar="ownerId") int q1, 

@MatrixVariable(name="q", pathVar="petId") int q2) { 


Uh GE == aia 
ff GP == 22 


[Original] A matrix variable may be defined as optional and a default value specified: 


你 也 可 以 声明 一 个 矩阵 变量 不 是 必须 出 现 的 ， 并 给 它 赋 一 个 默认 值 : 
// GET /pets/42 


@RequestMapping(path = "/pets/{petId}", method = RequestMethod.GET ) 
public void findPet(@MatrixVariable(required=false, defaultValue="1") int q) { 


// q == 


[Original] All matrix variables may be obtained in a Map: 


也 可 以 通过 一 个 Map 来 存储 所 有 的 矩阵 变量 : 


// GET /owners/42; q=11; r=12/pets/21; q=22; s=23 


@RequestMapping(path = "/owners/{ownerId}/pets/{petid}", method = RequestMethod.GET) 
public void findPet( 

@MatrixVariable Map<String, String> matrixVars, 

@MatrixVariable(pathVar="petId") Map<String, String> petMatrixVars) { 


He iebeiraweiess [Mey & sl 22]; Mie! § ale, Mogul’ seh 
7/ petMatrixVars: gi T1123 


[Original] Note that to enable the use of matrix variables, you must set the 
removeSemicolonContent property of RequestMappingHandlerMapping tO false . By 
default itis set to true . 


如 果 要 允许 矩阵 变量 的 使 用 ， 你 必须 把 RequestMappingHandlerMapping 类 
的 removeSemicoloncontent 属性 设置 为 false 。 该 值 默 认 是 true 的 。 
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使 用 @RequestMapping 注 解 映射 请 求 路 径 


[Original] The MVC Java config and the MVC namespace both provide options for 
enabling the use of matrix variables. 


MVC 的 Java 编 程 配 置 和 命名 空间 配置 都 提供 了 启用 算 阵 变量 的 方式 。 


[Original] If you are using Java config, The Advanced Customizations with MVC Java 
Config section describes how the RequestMappingHandlerMapping can be customized. 


如 果 你 是 使 用 Java 编 程 的 方式 ，“MVC Java 高 级 定制 化 配置 一 节 描 述 了 如 何 
对 RequestMappingHandlerMapping 进行 定制 。 


[Original] In the MVC namespace, the <mvc:annotation-driven> element has an 
enable-matrix-variables attribute that should be setto true . By default it is set to 


false . 


而 使 用 MVC 的 命名 空间 配置 时 ， 你 可 以 把 <mvc:annotation-driven> 元 素 下 的 enable- 
matrix-variables 属性 设置 为 true ° 该 值 默认 情况 下 是 配置 为 false 的 2 


<?xml version="1.0" encoding="UTF-8"?> 
<beans xmlns="http://www.springframework.org/schema/beans" 
xmlns:mvc="http://www.springframework .org/schema/mvc" 
xmlns:xsi="http://www.w3.0rg/2001/XMLSchema-instance" 
xsi:schemaLocation=" 
http://www. springframework.org/schema/beans 
http://www. springframework.org/schema/beans/spring-beans.xsd 
http://www. springframework.org/schema/mvc 
http://www. springframework.org/schema/mvc/spring-mvc.xsd"> 


<mvc:annotation-driven enable-matrix-variables="true"/> 


</beans> 


可 消费 的 媒体 类 型 


[Original] You can narrow the primary mapping by specifying a list of consumable media 


types. The request will be matched only if the Content-Type request header matches 
the specified media type. For example: 


你 可 以 指定 一 组 可 消费 的 媒体 类 型 ， 缩 小 映射 的 范围 。 这 样 只 有 当 请 求 头 中 Content-Type 的 


值 与 指定 可 消费 的 媒体 类 型 中 有 相同 的 时 候 ， 请 求 才 会 被 匹配 。 比 如 下 面 这 个 例子 : 
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使 用 @RequestMapping 注 解 映射 请 求 路 径 


@Controller 
@RequestMapping(path = "/pets", method = RequestMethod.POST, consumes="application/jso 
n") 
public void addPet(@RequestBody Pet pet, Model model) { 
// 方法 实现 省 略 


} 


[Original] Consumable media type expressions can also be negated as in !text/plain to 
match to all requests other than those with Content-Type of text/plain. Also consider 
using constants provided in MediaType such as APPLICATION_JSON_VALUE and 


APPLICATION_JSON_UTF8_VALUE . 


指定 可 消费 媒体 类 型 的 表达 式 中 还 可 以 使 用 否定 ， 比 如 ， 可 以 使 用 ltext/plain 来 匹配 所 有 请 求 
+ Content-Type Y * & text/plain 的 请 求 。 同 时 ， 在 mediatype 类 中 还 定义 了 一 些 常 量 ， 比 


如 APPLICATION_JSON_VALUE 、 APPLICATION_JSON_UTF8_VALUE 等 ， 推 荐 更 多 地 使 用 它们 。 


[Original] The consumes condition is supported on the type and on the method level. 
Unlike most other conditions, when used at the type level, method-level consumable 
types override rather than extend type-level consumable types. 


consumes 属性 提供 的 是 方法 级 的 类 型 支持 。 与 其 他 属性 不 同 ， 当 在 类 型 级 使 用 时 ， 方 
法 级 的 消费 类 型 将 履 盖 类 型 级 的 配置 ， 而 非 继承 关系 。 


可 生产 的 媒体 类 型 


[Original] You can narrow the primary mapping by specifying a list of producible media 
types. The request will be matched only if the Accept request header matches one of 
these values. Furthermore, use of the produces condition ensures the actual content 
type used to generate the response respects the media types specified in the produces 
condition. For example: 


你 可 以 指定 一 组 可 生产 的 媒体 类 型 ， 缩 小 映射 的 范围 。 这 样 只 有 当 请 求 头 中 Accept 的 值 与 指 
定 可 生产 的 媒体 类 型 中 有 相同 的 时 候 ， 请 求 才 会 被 匹配 。 而 且 ， 使 用 produces 条 件 可 以 确保 
用 于 生成 响应 (response) 的 内 容 与 指定 的 可 生产 的 媒体 类 型 是 相同 的 。 举 个 例子 : 


@Controller 
@RequestMapping(path = "/pets/{petId}", method = RequestMethod.GET, produces = MediaTy 
pe.APPLICATION_JSON_UTF8_VALUE) 
@ResponseBody 
public Pet getPet(@PathVariable String petId, Model model) { 
// 方法 实现 省 略 
} 
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使 用 @RequestMapping 注 解 映射 请 求 路 径 


[Original] Be aware that the media type specified in the produces condition can also 
optionally specify a character set. For example, in the code snippet above we specify 
the same media type than the default one configured in 


MappingJackson2HttpMessageConverter , including the utF-s charset. 


要 注意 的 是 ， 通 过 condition 条 件 指定 的 媒体 类 型 也 可 以 指定 字符 集 。 比 如 在 上 面 的 小 段 
代码 中 ， 我 们 还 是 履 写 了 MappingJackson2HttpMessageconverter 类 中 默认 配置 的 媒体 类 
型 ， 同 时 ， 还 指定 了 使 用 UTF-8 的 字符 集 。 

[Original] Just like with consumes, producible media type expressions can be negated 
as in !text/plain to match to all requests other than those with an Accept header value of 


text/plain. Also consider using constants provided in MediaType such as 


APPLICATION_JSON_VALUE and APPLICATION_JSON_UTF8_VALUE . 


与 consumes 条 件 类 似 ， 可 生产 的 媒体 类 型 表达 式 也 可 以 使 用 否定 。 上 比如 ， 可 以 使 用 


Itext/plain 来 匹配 所 有 请 求 头 Accept F RE text/plain 的 请 求 。 同 时 ， 在 mediaType 类 中 还 定 
义 了 一 些 常量 ， 比 如 APPLICATION_JSON_VALUE ` APPLICATION_JSON_UTF8_VALUE 等 ， 推 荐 更 多 地 


使 用 它们 。 


[Original] The produces condition is supported on the type and on the method level. 
Unlike most other conditions, when used at the type level, method-level producible 
types override rather than extend type-level producible types. 


produces 属性 提供 的 是 方法 级 的 类 型 支持 。 与 其 他 属性 不 同 ， 当 在 类 型 级 使 用 时 ， 方 法 
级 的 消费 类 型 将 覆盖 类 型 级 的 配置 ， 而 非 继 承 关系 。 


请 求 参 数 与 请 求 头 的 值 


[Original] You can narrow request matching through request parameter conditions such 
aS "myParam" , "!myParam" , Or "myParam=myValue" . The first two test for request 
parameter presence/absence and the third for a specific parameter value. Here is an 
example with a request parameter value condition: 


你 可 以 筛选 请 求 参 数 的 条 件 来 缩小 请 求 匹配 范围 ， 比 


如 "myParam" ` "ImyParam" 及 "myParam=myValue" 等 。 前 两 个 条 件 用 于 筛选 存在 /不 存在 某 些 


请 求 参数 的 请 求 ， 第 三 个 条 件 筛选 具有 特定 参数 值 的 请 求 。 下 面 有 个 例子 ， 展 示 了 如 何 使 用 
请 求 参数 值 的 第 选 条 件 : 
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使 用 @RequestMapping 注 解 映射 请 求 路 径 


@Controller 
@RequestMapping("/owners/{ownerId}") 
public class RelativePathUriTemplateController { 


@RequestMapping(path = "/pets/{petId}", method = RequestMethod.GET, params="myPara 
m=myValue") 


public void findPet(@PathVariable String ownerId, @PathVariable String petId, Mode 
1 model) { 


// 实际 实现 省 略 


[Original] The same can be done to test for request header presence/absence or to 
match based on a specific request header value: 


同样 ， 你 可 以 用 相同 的 条 件 来 算 选 请 求 头 的 出 现 与 否 ， 或 者 筛选 出 一 个 具有 特定 值 的 请 求 
Kk: 


@Controller 
@RequestMapping("/owners/{ownerlId}") 
public class RelativePathUriTemplateController { 


@RequestMapping(path = "/pets", method = RequestMethod.GET, headers="myHeader=myVa 
lue") 


public void findPet(@PathVariable String ownerId, @PathVariable String petId, Mode 
1 model) { 


// 方法 体 实 现 省 略 


[Original] Although you can match to Content-Type and Accept header values using 
media type wild cards (for example "content-type=text/*" will match to "text/plain" and 
"text/html", it is recommended to use the consumes and produces conditions 
respectively instead. They are intended specifically for that purpose. 


尽管 ， 你 可 以 使 用 媒体 类 型 的 通配符 (比如 "content-type=text/*") 来 匹配 请 求 头 
Content Type 和 Accept 的 值 ， 但 我 们 更 推荐 独立 使 用 consumes 和 proquces 条 件 来 筛选 
各 自 的 请 求 。 因 为 它们 就 是 专门 为 区 分 这 两 种 不 同 的 场景 而 生 的 。 
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21.3.3 定义 @RequestMapping 注 解 的 处 理 方 
法 (handler method) 


使 用 @RequestMapping 注解 的 处 理 方法 可 以 拥有 非常 灵活 的 方法 签名 ， 它 支持 的 方法 参数 及 返 
回 值 类 型 将 在 接 下 来 的 小 节 讲 述 。 大 多 数 参 数 都 可 以 任意 的 次 序 出 现 ， 除 了 唯一 的 一 个 例 
外 : BindingResult 参数 。 这 在 下 节 也 会 详细 描述 。 


Spring 3.1 中 新 增 了 一 些 类 ， 用 以 增强 注解 了 @RequestMapping 的 处 理 方 法 ， 分 别 

是 RequestMappingHandlerMapping 类 和 RequestMappingHandlerAdapter 类 。 我 们 鼓励 使 用 
这 组 新 的 类 ， 如 果 要 使 用 Spring 3.1 及 以 后 版 本 的 新 特性 ， 这 组 类 甚至 是 必须 使 用 的 。 这 
些 增强 类 在 MVC 的 命名 空 ae A 中 都 是 默认 开启 的 ， 如 果 不 
是 使 用 这 两 种 方法 ， 那 么 就 需要 显 式 地 配置 


支持 的 方法 参数 类 型 


下 面 列 出 所 有 支持 的 方法 参数 类 型 : 


。 请 求 或 响应 对 象 《Servlet API) 。 可 以 是 任何 具体 的 请 求 或 响应 类 型 的 对 象 ， 比 
如 ， ServletRequest 或 HttpServletRequest 对 象 等 S 

e HttpSession 类 型 的 会 话 对 象 (Servlet API) 。 使 用 该 类 型 的 参数 将 要 求 这 样 一 个 
Session 的 存在 ， 因 此 这 样 的 参数 永 不 为 null 。 


存 取 session 可 能 不 是 线程 安全 的 ， 特 别 是 在 一 个 Servlet 的 运行 环境 中 。 如 果 应 用 可 能 有 
多 个 请 求 同 时 并 发 存 取 一 个 session 场 景 ， 请 考虑 将 RequestMappingHandlerAdapter 类 
中 的 "synchronizeOnSession" 标 志 设 置 为 "true"。 


©® org.springframework.web.context.request.WebRequest 或 org.springframework.web.context 

.request.NativeWebRequest ° 允许 存 取 一 般 的 请 求 参 数 和 请 RIZE J 包围 的 属性 
(attribute) ， 同 时 无 需 绑 定 使 用 Servlet/Portlet 的 API 

e。 当前 请 求 的 地 区 信息 java.util.Locale ， 由 已 配置 的 最 相关 的 地 区 解析 器 解析 得 到 。 在 
MVC 的 环境 下 ， 就 是 应 用 中 配置 的 LocaleResolver 或 LocaleContextResolver 

。 与 当前 请 求 绑 定 的 时 区 信息 java.util.TimeZone (java 6 以 上 的 版 
本 ) / java.time.ZoneId (java 8) ， 由 LocalecontextResolver 解析 得 到 

e 用 于 存 取 请 求 正 文 的 java.io.InputStream 或 java.io.Reader 。 该 对 象 与 通过 Servlet API 
拿 到 的 输入 流 /Reader 是 一 样 的 

e。 用 于 生成 响应 正文 的 java.io.OutputStream 或 java.io.Writer ° 该 对 象 与 通过 Servlet 
API 拿 到 的 输出 流 /Writer 是 一 样 的 

e org.springframework.http.HttpMethod 。 可 以 拿 到 HTTP 请 求 方法 

e 包装 了 当前 被 认证 用 户 信息 的 java.security.Principal 


带 @Pathvariable 注解 的 方法 参数 ， 其 存放 了 URI 模 板 变量 中 的 值 。 详 见 “"URI 模 板 变量 "一 
a 

带 @MatrixVariable EAN Y kA o HEMT URIBE OM o FLEES 
量 " 一 节 

带 @RequestParam 注解 的 方法 参数 ， 其 存放 了 Servlet 请 求 中 所 指定 的 参数 。 参 数 的 值 会 被 
转换 成 方法 参数 所 声明 的 类 型 。 详 见 “ 使 用 @RequestParam 注 解 绑 定 请 求 参数 至 方法 参 
数 ” 一 节 

带 @RequestHeader 注解 的 方法 参数 ， 其 存放 了 Servlet 请 求 中 所 指定 的 HTTP 请 求 头 的 值 。 
参数 的 值 会 被 转换 成 方法 参数 所 声明 的 类 型 。 详 见 " 使 用 @RequestHeader 注 解 映射 请 求 
头 属性 "一 节 . 

带 @RequestBody 注解 的 参数 ， 提 供 了 对 HTTP 请 求 体 的 存 取 。 参 数 的 值 通 

过 HttpMessageConverter 被 转换 成 方法 参数 所 声明 的 类 型 。 详 见 “ 使 用 @RequestBody 注 
解 映射 请 求 体 "一 节 " 

带 @RequestPart 注解 的 参数 ， 提 供 了 对 一 个 "multipart/form-data 请 求 块 (request part) 
内 容 的 存 取 。 更 多 的 信息 请 参考 21.10.5 “处理 客 户 端 文件 上 传 的 请 求 "一 节 和 21.10 
“Spring 对 多 部 分 文件 上 传 的 支持 "一 节 

HttpEntity<?> 类 型 的 参数 ， 其 提供 了 对 HTTP 请 求 关 和 请 求 内 容 的 存 取 。 请 求 流 是 通 

过 HttpMessageConverter 被 转换 成 entity 对 象 的 。 详 见 “HttpEntity ”一 节 

java.util.Map / org.springframework.io.Model / org.springframework.ui.ModelMap 类 型 的 
参数 ， 用 以 增强 默认 暴露 给 视图 层 的 模型 (model) 的 功能 
org.springframework.web.servlet.mvc.support.RedirectAttributes 类 型 的 参数 ， 用 以 指定 
重 定向 下 要 使 用 到 的 属性 集 以 及 添加 flash 属 性 〈 暂 存在 服务 端的 属性 ， 它 们 会 在 下 次 重 
定向 请 求 的 范围 中 有 效 ) 。 详 见 " 向 重 定向 请 求 传递 参数 "一 节 

命令 或 表单 对 象 ， 它 们 用 于 将 请 求 参 数 直接 绑 定 到 bean 字 段 〈( 可 能 是 通过 setter 方 法 ) 。 
你 可 以 通过 @InitBinder 注解 和 /或 HanderAdapter 的 配置 来 定制 这 个 过 程 的 类 型 转换 。 具 
体 请 参考 RequestMappingHandlerAdapter 类 webBindingInitializer 属性 的 文档 。 这 样 的 命 
令 对 象 ， 以 及 其 上 的 验证 结果 ， 默 认 会 被 添加 到 模型 model 中 ， 键 名 默认 是 该 命令 对 得 类 
的 类 名 一 一 比如 ， some.package.orderAddress 类 型 的 命令 对 象 就 使 用 属性 

名 orderAddress 类 获取 。 ModelAttribute 注解 可 以 应 用 在 方法 参数 上 ， 用 以 指定 该 模型 
所 用 的 属性 名 

org.springframework.validation.Errors / 

org.springframework.validation.BindingResult 验证 结果 对 象 ? 用 于 存储 前 面 的 命令 或 表 
单 对 象 的 验证 结果 〈 紧 接 其 前 的 第 一 个 方法 参数 ) © 
org.springframework.web.bind.support.SessionStatus 对 象 ， 用 以 标记 当 前 的 表单 处 理 已 
结束 。 这 将 触发 一 些 清理 操作 : @sessionattributes 在 类 级 别 注解 的 属性 将 被 移 除 
org.springframework.web.util.UriComponentsBuilder 构造 器 对 象 ， 用 于 构造 当 前 请 求 URL 
相关 的 信息 ， 比 如 主机 名 、 端 口号 、 资 源 类 型 (scheme) 、 上 下 文 路 径 、servlet 映 射 中 
的 相对 部 分 (literal part) 等 


在 参数 列表 中 ， Errors 或 BindingResult 参数 必须 紧 跟 在 其 所 绑 定 的 验证 对 象 后 面 。 这 是 因 
为 ， 在 参数 列表 中 允许 有 多 于 一 个 的 模型 对 象 ，Spring 会 为 它们 创建 不 同 的 BindingResult X 
例 。 因 此 ， 下 面 这 样 的 代码 是 不 能 工作 的 : 


BindingResult 与 @ModelAttribute 错 误 的 参数 次 序 


@RequestMapping(method = RequestMethod.POST) 


public String processSubmit(@ModelAttribute("pet") Pet pet, Model model, BindingResult 
result) Ar? 


上 例 中 ， 因 为 在 模型 对 象 pet 和 验证 结果 对 象 BindingResult 中 间 还 插 了 一 个 model 参数 ， 
这 是 不 行 的 。 要 达到 预期 的 效果 ， 必 须 调整 一 下 参数 的 次 序 : 


@RequestMapping(method = RequestMethod.POST) 


public String processSubmit(@ModelAttribute("pet") Pet pet, BindingResult result, Mode 
1 model) { ... } 


对 于 一 些 带 有 required 属性 的 注解 (比如 @RequestParam ` @RequestHeader +) > JDK 
1.8 的 java.util.0ptional 可 以 作为 被 它们 注解 的 方法 参数 。 在 这 种 情况 下 ， 使 
用 java.util.Optional 与 required=false 的 作用 是 相 同 的 。 


支持 的 方法 返回 类 型 


以 下 是 handler 方 法 允许 的 所 有 返回 类 型 : 


e ModelAndview 对 象 ， 其 中 model 隐 含 填 充 了 命令 对 象 ， 以 及 注解 了 @modelattribute 字段 
的 存 取 器 被 调用 所 返回 的 值 。 

© Model 对 象 ， 其 中 视图 名 称 默 认 由 RequestToViewNameTranslator 决定 ，model 隐 含 填充 了 
命令 对 象 以 及 注解 了 @ModelAttribute 字段 的 存 取 器 被 调用 所 返回 的 值 

e Map 对 象 ， 用 于 暴露 model， 其 中 视图 名 称 默 认 由 Request ToViewNameTranslator RE? 
model 隐 含 填充 了 命令 对 象 以 及 注解 了 @modelattribute 字段 的 存 取 器 被 调用 所 返回 的 值 

© view 对 象 。 其 中 model 隐 含 填 充 了 命令 对 象 ， 以 及 注解 了 @ModelAttribute 字段 的 存 取 
器 被 调用 所 返回 的 值 。handler 方 法 也 可 以 增加 一 个 Model 类 型 的 方法 参数 来 增强 model 

® String 对 象 ， 其 值 会 被 解析 成 一 个 逻辑 视图 名 。 其 中 ，model 将 默认 填充 了 命令 对 象 以 
及 注解 了 @ModelAttribute 字段 的 存 取 器 被 调用 所 返回 的 值 。handler 方 法 也 可 以 增加 一 
个 Model 类 型 的 方法 参数 来 增强 model 

© void 。 如 果 处 理 器 方法 中 已 经 对 response 响 应 数据 进行 了 处 理 (比如 在 方法 参数 中 定义 
=A ServletResponse 或 HttpServletResponse RAHBZAF BEDE ALAPS K 
A) ， 那 么 方法 可 以 返回 void。handler 方 法 也 可 以 增加 一 个 Model 类 型 的 方法 参数 来 增 
强 model 

© 如 果 处 理 器 方法 注解 了 ResponseBody ， 那 么 返回 类 型 将 被 写 到 HTTP 的 响应 体 中 ， 而 返回 


值 会 被 HttpMessageConverters 转换 成 所 方法 声 明 的 参数 类 型 2 详 见 使 
用 "@ResponseBody 注 解 映 射 响应 体 " 一 节 

e HttpEntity<?> 或 ResponseEntity<?> 对 象 ， 用 于 提供 对 Servlet HTTP 响 应 头 和 响应 内 容 
的 存 取 。 对 象 体 会 被 HttpMessageConverters 转换 成 响应 流 。 详 见 使 用 HttpEntity 一 节 

e HttpHeaders 对 象 ， 返 回 一 个 不 含 响 应 体 的 response 

e Callable<?> 对 象 。 当 应 用 希望 异步 地 返回 方法 值 时 使 用 ， 这 个 过 程 由 Spring MVC 自 身 
的 线程 来 管理 

e DeferredResult<?> 对 象 。 当 应 用 希望 方法 的 返回 值 交 由 线程 自身 决定 时 使 用 

e ListenableFuture<?> 对 象 。 当 应 用 希望 方法 的 返回 值 交 由 线程 自身 决定 时 使 用 

© ResponseBodyEmitter 对 象 ， 可 用 它 异 步 地 向 响应 体 中 同时 写 多 个 对 象 ，also supported 
as the body within a ResponseEntity 

© sseemitter 对 象 ， 可 用 它 异 步 地 向 响应 体 中 写 服务 器 端 事件 (Server-Sent 
Events) ,also supported as the body within a ResponseEntity 

© sStreamingResponseBody 对 象 ， 可 用 它 异 步 地 向 响应 对 象 的 输出 流 中 写 东 西 。also 
supported as the body within a ResponseEntity 

o 其 他 任何 返回 类 型 ， 都 会 被 处 理 成 model 的 一 个 属性 并 返回 给 视图 ， 该 属性 的 名 称 为 方法 
级 的 @Modelattribute 所 注解 的 字段 名 (或 者 以 返回 类 型 的 类 名 作为 默认 的 属性 名 ) © 
model 隐 含 填充 了 命令 对 象 以 及 注解 了 @ModelAttribute 字段 的 存 取 器 被 调用 所 返回 的 值 


使 用 @RequestParam 将 请 求 参 数 绑 定 至 方法 参数 


你 可 以 使 用 @RequestParam 注解 将 请 求 参 数 绑 定 到 你 控制 器 的 方法 参数 上 。 


下 面 这 段 代码 展示 了 它 的 用 法 : 


@Controller 
@RequestMapping("/pets") 
@SessionAttributes("pet") 
public class EditPetForm { 
Eien 
@RequestMapping(method = RequestMapping.GET) 
public String setupForm(@RequestParam("petId") int petId, ModelMap model) { 
Pet pet = this.clinic.loadPet(petId); 
model.addAttribute("pet", pet); 
return "petForm"; 


oe 


若 参 数 使 用 了 该 注解 ， 则 该 参数 默认 是 必须 提供 的 ， 但 你 也 可 以 把 该 参数 标注 为 非 必 须 的 : 
只 需要 将 @RequestParam 注解 的 required 属性 设置 为 false 即 可 ( #6 


如 ， @RequestParam(path="id", required=false) ) 2 


若 所 注解 的 方法 参数 类 型 不 是 string ， 则 类 型 转换 会 自动 地 发 生 。 详 见 "方法 参数 与 类 型 转 
换 " 一 节 


= @RequestParam 注解 的 参数 类 型 是 Map<String, String> 或 者 MultiValueMap<String, 
String> ， 则 该 Map 中 会 自动 填充 所 有 的 请 求 参 数 。 


使 用 @RequestBody 注 解 映 射 请 求 体 
方法 参数 中 的 @RequestBody 注解 暗示 了 方法 参数 应 该 被 绑 定 了 HTTP 请 求 体 的 值 。 举 个 例子 : 


@RequestMapping(path = "/something", method = RequestMethod. PUT) 
public void handle(@RequestBody String body, Writer writer) throws IOException { 
writer .write(body); 


请 求 体 到 方法 参数 的 转换 是 由 HttpMessageConverter 完成 的 ° HttpMessageConverter 负 责 将 
HTTP 请 求 信息 转换 成 对 象 ， 以 及 将 对 象 转换 回 一 个 HTTP 响 应 体 。 对 于 @RequestBody 注 
解 ” RequestMappingHandlerAdapter 提供 了 以 下 几 种 默认 的 HttpMessageConverter 支持 : 


è ByteArrayHttpMessageConverter 用 以 转换 字 节 数组 

@ StringHttpMessageConverter 用 以 转换 字符 串 

@ FormHttpMessageConverter 用 以 将 表格 数据 转换 成 MultiValueMap<String, String> 或 
从 multivalueMap<String, String> 中 转换 出 表格 数据 


@ SourceHttpMessageConverter 用 于 javax.xml.transform.Source 类 的 互相 转换 


关于 这 些 转换 器 的 更 多 信息 ， 请 参考 "HTTP 信 息 转 换 器 "一 节 。 另 外 ， 如 果 使 用 的 是 MVC 命 名 
空间 或 Java 编 程 的 配置 方式 ， 会 有 更 多 默认 注册 的 消息 转换 器 。 更 多 信息 ， 请 参考 "启用 MVC 
Java 编 程 配置 或 MVC XML 命令 空间 配置 "一 节 。 


若 你 更 倾向 于 阅读 和 编写 XML 文件 ， 那 么 你 需要 配置 一 个 MarshallingHttpMessageConverter 并 
为 其 提供 org.springframework.oxm ae Marshaller 和 Unmarshaller 实现 。 下 面 的 示例 


就 为 ee 直接 在 配置 文件 中 配置 它 。 但 如 果 你 的 应 用 是 使 用 MVC 命 令 空 间或 MVC Java 
编程 的 方式 进行 配置 的 ， 则 请 参考 "局 aa Java 编 程 配置 或 MVC XML 命令 空间 配置 "这 


P o 


<bean class="org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandl 
erAdapter"> 
<property name="messageConverters"> 
<util:list id="beanList"> 
<ref bean="stringHttpMessageConverter"/> 
<ref bean="marshallingHttpMessageConverter"/> 
</util:list> 
</property 
</bean> 


<bean id="stringHttpMessageConverter" class="org.springframework.http.converter.String 
HttpMessageConverter"/> 


<bean id="marshallingHttpMessageConverter" 
class="org.springframework.http.converter.xml.MarshallingHttpMessageConverter" 


> 
<property name="marshaller" ref="castorMarshaller"/> 
<property name="unmarshaller" ref="castorMarshaller"/> 
</bean> 


<bean id="castorMarshaller" class="org.springframework.oxm.castor.CastorMarshaller"/> 


注解 了 @RequestBody 的 方法 参数 还 @Valid 注解 ， 这 样 框架 会 使 用 已 配置 

的 Validator 实例 来 对 该 参数 进行 验 若 你 的 应 用 是 使 用 MVC 命 令 空 间或 MVC Java 编 程 的 
方式 配置 的 ， 框 架 eee N a 个 符 合 JSR-303 规 范 的 验证 器 ， 并 自动 将 

其 作为 默认 配置 


与 @Modelattribute 注解 的 参数 一 样 ，Errors 也 可 以 被 传 入 为 方法 参数 ， 用 于 检查 错误 。 
果 没 有 上 声 明 这 文 样 一 个 参数 ， 那么 么 程序 会 会 抛 出 一 个 MethodArgumentNotValidException 异常 党 
常 默 认 由 DefaultHandlerExceptionResolver 处 理 ， 处 理 程序 会 返回 一 个 400 错误 给 客户 端 。 


关于 如 何 通 过 MVC 命 令 空 间或 MVC Java 编 程 的 方式 配置 消息 转换 器 和 验证 器 ， 也 请 参 
考 "启用 MVC Java 编 程 配置 或 MVC XML 命令 空间 配置 "一 节 。 


使 用 @ResponseBody 注 解 映射 响应 体 


@ResponseBody 注解 与 @RequestBody 注解 类 似 。 @ResponseBody 注解 可 被 应 用 于 方法 上 ， 标 志 
该 方法 的 返回 值 (更 正 ， 原 文 是 return type， 看 起 来 应 该 是 返回 值 ) 应 该 被 直接 写 回 到 HTTP 
响应 体 中 去 (而 不 会 被 被 放置 到 Model 中 或 被 解释 为 一 个 视图 名 ) 。 举 个 例子 : 


@RequestMapping(path = "/something", method = RequestMethod. PUT) 
@ResponseBody 
public String helloworld() { 

return "Hello World" 


上 面 的 代码 结果 是 文本 Hello world 将 被 写 入 HTTP 的 响应 流 中 。 


与 @RequestBody 注解 类 似 ，Spring 使 用 了 一 个 HttpMessageConverter 来 将 返回 对 象 转换 到 响 
应 体 中 。 关 于 这 些 转换 器 的 更 多 信息 ， 请 参考 "HTTP 信 息 转换 器 "一 节 。 


使 用 @RestController 注 解 创建 REST 控 制 器 


当今 让 控制 器 实现 一 个 REST APl 是 非常 常见 的 ， 这 种 场景 下 控制 器 只 需要 提供 JSON ` XML 
或 其 他 自 定义 的 媒体 类 型 内 容 即 可 。 你 不 需要 在 每 个 @RequestMapping 方法 上 都 增加 一 
个 @ResponseBody 注解 ， 更 简明 的 做 法 是 ， 给 你 的 控制 器 加 上 一 个 @Restcontroller 的 注解 。 


@RestController 是 一 个 原生 内 置 的 注解 ， 它 结合 了 @ResponseBody 与 @Controller 注解 的 功 
能 。 不 仅 如 此 ， 它 也 让 你 的 控制 器 更 表 义 ， 而 且 在 框架 未 来 的 发 布 版 本 中 ， 它 也 可 能 承载 更 
多 的 意义 。 

OWS 


与 普通 的 @Controller KF 2 @RestController 也 可 以 与 @ControllerAdvice bean Bt Mz A] ° 
更 多 细节 ， 请 见 使 用 @ControllerAdvice 辅 助 控制 器 。 


使 用 HTTP 实 体 HttpEntity 


HttpEntity 与 @RequestBody 和 @ResponseBody 很 相似 。 除 了 能 获得 请 求 体 和 响应 体 中 的 内 容 
之 外 ， HttpEntity (以 及 专门 负责 处 理 响 应 的 ResponseEntity 子 类 ) 还 可 以 存 取 请 求 头 和 响 
应 头 ， 像 下 面 这 样 : 


@RequestMapping("/something") 
public ResponseEntity<String> handle(HttpEntity<byte[]> requestEntity) throws Unsuppor 
tedEncodingException { 
String requestHeader = requestEntity.getHeaders().getFirst("MyRequestHeader"); 
byte[] requestBody = requestEntity.getBody(); 


// do something with request header and body 


HttpHeaders responseHeaders = new HttpHeaders(); 
responseHeaders.set("MyResponseHeader", "MyValue"); 
return new ResponseEntity<String>("Hello World", responseHeaders, HttpStatus.CREAT 
ED); 
} 


上 面 这 段 示 例 代 码 先是 获取 了 MyRequestHeader 请 求 头 的 值 ， 然 后 读 取 请 求 体 的 主体 内 容 。 读 
完 以 后 往 影 响 头 中 添加 了 一 个 自己 的 响应 头 MyResponseHeader ， 然后 向 响应 流 中 写 了 字符 
# Hello world ， 最 后 把 响应 状态 码 设置 为 201 (创建 成 功 ) 。 


与 @RequestBody 与 @ResponseBody 注解 一 样 Spring 使 用 了 HttpMessageConverter 来 对 请 求 流 
和 响应 流 进行 转换 。 关 于 这 些 转换 器 的 更 多 信息 ， 请 阅读 上 一 小 节 以 及 "HTTP 信 息 转换 器 "这 


一 节 。 


对 方法 使 用 @ModelAttribute 注 解 


@ModelAttribute 注解 可 被 应 用 在 方法 或 方法 参数 上 。 本 节 将 介绍 其 被 注解 于 方法 上 时 的 用 
法 ， 下 节 会 介绍 其 被 用 于 注解 方法 参数 的 用 法 。 


注解 在 方法 上 的 @ModelAttribute 说 明了 方法 的 作用 是 用 于 添加 一 个 或 多 个 属性 到 model 上 。 
这 样 的 方法 能 接受 与 @RequestMapping 注解 相同 的 参数 类 型 ， 只 不 过 不 能 直接 被 映射 到 具体 的 
请 求 上 。 在 同一 个 控制 器 中 ， 注 解 了 @ModelAttribute 的 方法 实际 上 会 在 @RequestMapping 方 
法 之 前 被 调用 。 以 下 是 几 个 例子 : 


// Add one attribute 
// The return value of the method is added to the model under the name "account" 
// You can customize the name via @ModelAttribute("myAccount") 


@ModelAttribute 
public Account addAccount(@RequestParam String number) { 
return accountManager .findAccount (number); 


// Add multiple attributes 


@ModelAttribute 
public void populateModel(@RequestParam String number, Model model) { 
model.addAttribute(accountManager .findAccount (number ) ); 


// add more ... 


@ModelAttribute 方法 通常 被 用 来 填充 一 些 公共 需要 的 属性 或 数据 ， 比 如 一 个 下 拉 列 表 所 预 设 
的 几 种 状态 ， 或 者 宠物 的 几 种 类 型 ， 或 者 去 取得 一 个 HTML 表 单 泻 染 所 需要 的 命令 对 象 ， 比 
如 Account 等 8 


留意 @ModelAttribute 方法 的 两 种 风格 。 在 第 一 种 写 法 中 ? 方法 通过 返回 值 的 方式 默认 地 将 添 
加 一 个 属性 ; 在 第 二 种 写法 中 ， 方 法 接收 一 个 model 对 象 ， 然 后 可 以 向 其 中 添加 任意 数量 的 
属性 。 你 可 以 在 根据 需要 ， 在 两 种 风格 中 选择 合适 的 一 种 。 


一 个 控制 器 可 以 拥有 数量 不 限 的 @ModelAttribute 方法 。 同 个 控 器 内 的 所 有 这 些 方 法 ， 都 会 


在 @RequestMapping 方法 之 前 前 被 调用 。 


@ModelAttribute 方法 也 可 以 定义 在 @controllerAdvice 注解 的 类 中 ， 并 且 这 
些 @ModelAttribute 可 以 同时 对 许 多 控制 器 生效 。 上 有 具体 的 信息 可 以 参考 使 用 
@ControllerAdvice 辅 助 控制 器 


属性 名 没有 被 显 式 指定 的 时 候 又 当 如 何 呢 ? 在 这 种 情况 下 ， 框 架 将 根据 属性 的 类 型 给 予 
一 个 默认 名 称 。 举 个 例子 ， 若 方法 返回 一 个 account 类 型 的 对 象 ， 则 默认 的 属性 名 

为 "account"。 你 可 以 通过 设置 @ModelAttribute 注解 的 值 来 改变 默认 值 。 当 向 Model 中 

直接 添加 属性 时 ， 请 使 用 合适 的 重 载 方法 addAttribute( - 即 ， 带 或 不 带 属 性 名 的 方 

法 。 


@ModelAttribute 注解 也 可 以 被 用 在 @RequestMapping 方法 上 。 这 种 情况 

T > @RequestMapping 方法 的 返回 值 将 会 被 解释 为 model 的 一 个 属性 ， 而 非 一 个 视图 名 。 a 
视图 名 将 以 视图 命名 约定 来 方式 来 决议 ， 与 返回 值 为 void 的 方法 所 采用 的 处 理 方法 类 似 
见 视图 : 请 求 与 视图 名 的 对 应 。 





在 方法 参数 上 使 用 @ModelAttribute 注 解 


如 上 一 小 节 所 解释 ， @ModelAttribute 注解 既 可 以 被 用 在 方法 上 ， 也 可 以 被 用 在 方法 参数 上 。 
这 一 小 节 将 介绍 它 注 解 在 方法 参数 上 时 的 用 法 。 


注解 在 方法 参数 上 的 @ModelAttribute 说 明了 该 方法 参数 的 值 将 由 model 中 取得 。 如 果 model 
中 找 不 到 ， 那 么 该 参数 会 先 被 实例 化 ， 然 后 被 添加 到 model 中 。 在 model 中 存在 以 后 ， 请 求 中 
所 有 名 称 匹 配 的 参数 都 会 填充 到 该 参数 中 。 这 在 Spring MVC 中 被 称 为 数据 绑 定 ， 一 个 非常 有 
用 的 特性 ， 节 约 了 你 每 次 都 需要 手动 从 表格 数据 中 转换 这 些 字段 数据 的 时 间 。 


@RequestMapping(path = "/owners/{ownerId}/pets/{petId}/edit", method = RequestMethod.P 
OST) 
public String processSubmit(@ModelAttribute Pet pet) { } 


以 上 面 的 代码 为 例 ， 这 个 Pet 类 型 的 实例 可 能 来 自 哪 里 呢 ? 有 几 种 可 能 


e 它 可 能 因为 @sessionAttributes 注解 的 使 用 已 经 存在 
A aol ahi ne 注解 ， 使 用 HTTP 会 话 保存 模型 数据 "一 节 

e 能 因为 在 同 个 控制 器 中 使 用 了 @modelattribute 方法 已 经 存在 于 model 中 一 正如 上 
ae 

。 它 可 能 是 由 URI 模 板 变 量 和 类 型 转换 中 取得 的 (下 面 会 详细 讲解 ) 

© 它 可 能 是 调用 了 自身 的 默认 构造 器 被 实例 化 出 来 的 


见 " 在 请 求 之 间 使 





@ModelAttribute 方法 常 用 于 从 数据 库 中 取 一 个 属 性 值 ? 该 值 可 能 通过 W @SessionAttributes 注 
解 在 请 求 中 间 ft 。 在 一 些 情况 下 ， 使 用 URI 模 板 变 量 和 类 型 转换 的 方式 来 取得 一 个 属性 是 更 
方便 的 方式 。 这 里 有 个 例子 : 


@RequestMapping(path = "/accounts/{account}", method = RequestMethod. PUT) 
public String save(@ModelAttribute("account") Account account) { 


} 


上 面 这 个 例子 中 ，model 属 性 的 名 称 〈"account") 与 URI 模 板 变 量 的 名 称 相 匹 配 。 如 果 你 配置 
了 一 个 可 以 将 String 类 型 的 账户 值 转换 成 Account 类 型 实例 的 转换 器 Converter<String, 
Account> ， 那 么 上 面 这 段 代 码 就 可 以 工作 的 很 好 ， 而 不 需要 再 额外 写 一 个 @modelattribute X 
法 。 


下 一 步 就 是 数据 的 绑 定 ° WebDataBinder 类 能 将 请 求 参 数 一 一 包括 字符 串 的 查询 参数 和 表单 字 
段 等 一 一 通过 名 称 匹 配 到 model 的 属性 上 。 成 功 匹 配 的 字段 在 需要 的 时 候 会 进行 一 次 类 型 转换 
(从 String 类 型 到 目标 字段 的 类 型 ) ， 然 后 被 填充 到 model 对 应 的 属性 中 。 数 据 绑 定 和 数据 验 
证 的 问题 在 第 8 齐 验证 ， 数 据 绑 定 和 类 型 转换 中 提 到 。 如 何在 控制 器 层 来 定制 数据 绑 定 的 过 

程 ， 在 这 一 节 "定制 WebDataBinder 的 初始 化 "中 提 及 。 


进行 了 数据 绑 定 后 ， 则 可 能 会 出 现 一 些 错误 ， 比 如 没有 提供 必须 的 字段 、 类 型 转换 过 程 的 错 
误 等 。 若 想 检 查 这 些 错误 ， 可 以 在 注解 了 emodelattribute 的 参数 紧 跟 着 声明 一 


个 BindingResult BR: 


@RequestMapping(path = "/owners/{ownerlId}/pets/{petId}/edit", method = RequestMethod.P 
OST) 
public String processSubmit(@ModelAttribute("pet") Pet pet, BindingResult result) { 
if (result.hasErrors()) { 
return "petForm"; 


} 


WUE ot 


拿 到 BindingResult 参数 后 ， 你 可 以 检查 是 否 有 错误 。 有 时 你 可 以 通过 Spring 的 <errors> X 
单 标签 来 在 同一 个 表单 上 显示 错误 信息 。 


BindingResult 被 用 于 记录 数据 绑 定 过 程 的 错误 ， 因 此 除了 数据 绑 定 外 ， 你 还 可 以 把 该 对 象 传 
给 自己 定制 的 验证 器 来 调用 验证 。 这 使 得 数据 绑 定 过 程 和 验证 过 程 出 现 的 错误 可 以 被 搜集 到 
一 处 ， 然 后 一 并 返回 给 用 户 : 


@RequestMapping(path = "/owners/{ownerlId}/pets/{petId}/edit", method = RequestMethod.P 
OST) 
public String processSubmit(@ModelAttribute("pet") Pet pet, BindingResult result) { 


new PetValidator().validate(pet, result); 
if (result.hasErrors()) { 
return "petForm"; 


} 


WIE an 


又 或 者 ， 你 可 以 通过 添加 一 个 JSR-303 规 范 的 evalid 注解 ， 这 样 验证 器 会 自动 被 调用 。 


@RequestMapping(path = "/owners/{ownerId}/pets/{petId}/edit", method = RequestMethod.P 
OST) 


public String processSubmit(@Valid @ModelAttribute("pet") Pet pet, BindingResult resul 
et 


if (result.hasErrors()) { 
return "petForm"; 


} 


关于 如 何 配置 并 使 用 验证 ， 可 以 参考 第 8.8 小 节 "Spring 验证 "和 第 8 章 验证 ， 数 据 绑 定 和 类 型 
转换 。 


在 请 求 之 间 使 用 @SessionAttributes 注 解 ， 使 用 
HTTP 会 话 保存 模型 数据 


类 型 级 别 的 @sessionattributes 注解 声明 了 某 个 特定 处 理 器 所 使 用 的 会 话 属性 。 通 常 它 会 列 
出 该 类 型 希望 存储 到 Session 或 converstaion 中 的 model 属 性 名 或 model 的 类 型 名 ， 一 般 是 用 于 
在 请 求 之 间 保 存 一 些 表单 数据 的 bean。 


以 下 的 代码 段 演 示 了 该 注解 的 用 法 ， 它 指定 了 模型 属性 的 名 称 


@Controller 

@RequestMapping("/editPet.do") 

@SessionAttributes("pet") 

public class EditPetForm { 
人 


i$ A "application/x-www-form-urlencoded" %4% 


上 一 小 节 讲 述 了 如 何 使 用 @Modelattribute 支持 客户 端 浏览 器 的 多 次 表单 提交 请 求 。 对 于 不 是 
使 用 的 浏览 器 的 客户 端 ， 我 们 也 推荐 使 用 这 个 注解 来 处 理 请 求 。 但 当 请 求 是 一 个 HTTP PUT 方 
法 的 请 求 时 ， 有 一 个 事情 需要 注意 。 浏 览 器 可 以 通过 HTTP 的 GET 方 法 或 POST 方法 来 提交 
单数 据 ， 非 浏览 器 的 客户 端 还 可 以 通过 HTTP 的 PUT 方法 来 提交 表单 。 这 就 设计 是 个 挑战 ， 
为 在 Servlet 规 范 中 明 确 规定 ” ServletRequest.getParameter*() 系 列 的 方法 只 能 支持 通过 
HTTP POST 方法 的 方式 提交 表单 ， 而 不 支持 HTTP PUT 的 方式 。 


为 了 支持 HTTP 的 PUT 类 型 和 PATCH 类 型 的 请 求 ，Spring 的 spring-web 模块 提供 了 一 个 过 滤 


ua 


器 HttpPutFormContentFilter 。 你 可 以 在 web.xml 文件 中 配置 它 


<filter> 
<filter -name>httpPutFormFilter</filter -name> 


<filter-class>org.springframework.web.filter.HttpPutFormContentFilter</filter- 
class> 


</filter> 


<filter -mapping> 
<filter -name>httpPutFormFilter</filter -name> 
<servlet -name>dispatcherServlet</servlet-name> 
</filter-mapping> 


<servlet> 
<servlet -name>dispatcherServlet</servlet-name> 
<servlet-class>org.springframework.web.servlet .DispatcherServlet</servlet-class 


</servlet> 
BE S O 


上 面 的 过 滤器 将 会 拦截 内 容 类 型 (content type)» NA ~ HTTP 
方法 为 PUT 或 PATCH 类 型 的 请 求 ， 然 后 从 请 求 体 中 读 取 表 单数 据 ， 把 它们 包 

在 ServletRequest 中 。 这 是 为 了 使 表单 数据 能 够 通过 ServletRequest.getParameter*() 系列 的 
方法 来 拿 到 。 


为 HttpPutFormContentFilter 会 消费 请 求 体 的 内 容 ， 此 ， 它 不 应 该 用 于 处 理 那些 依赖 


ua 


FH application/x-ww-form-urlencoded 转换 器 的 PUT 和 PATCH 请 求 ， 这 包括 
了 @RequestBodyMultiValueMap<String, String> 和 HttpEntity<MultiValueMap<String, 


Strings> ° 


使 用 @CookieValue 注 解 映射 cookie 值 


@cookievalue 注解 能 将 一 个 方法 参数 与 一 个 HTTP cookie 的 值 进 行 绑 定 。 


看 一 个 这 样 的 场景 : 以 下 的 这 个 cookie 存 储 在 一 个 HTTP 请 求 中 : 


JSESSIONID=415A4AC17 8CS59DACEOB2C9CA727CDD84 


下 面 的 代码 演示 了 拿 到 JsESsIONID 这 个 cookie 值 的 方法 : 


@RequestMapping("/displayHeaderInfo.do") 
public void displayHeaderInfo(@CookieValue("JSESSIONID") String cookie) { 
Lha 


若 注 解 的 目标 方法 参数 不 是 string 类 型 ， 则 类 型 转换 会 自动 进行 。 详 见 "方法 参数 与 类 型 转 
换 "一 闻 。 


这 个 注解 可 以 注解 到 处 理 器 方法 上 ， 在 Servlet 环 境 和 Portlet 环 境 都 能 使 用 。 


使 用 @RequestHeader 注解 映射 请 求 头 属性 


@RequestHeader 注解 能 将 一 个 方法 参数 与 一 个 请 求 头 属性 进行 绑 定 。 


以 下 是 一 个 请 求 头 的 例子 : 


Host localhost : 8080 

Accept text/html, application/xhtml+xml, application/xml;q=0.9 
Accept -Language fr,en-gb;q=0.7,en;q=0.3 

Accept-Encoding gzip,deflate 

Accept-Charset IS0-8859-1,utf-8;q=0.7,*;q=0.7 

Keep-Alive 300 


以 下 的 代码 片段 展示 了 如 何 取 得 Accept-Encoding 请 求 头 和 Keep-Alive 请 求 头 的 值 : 


@RequestMapping("/displayHeaderInfo.do") 
public void displayHeaderInfo(@RequestHeader ("Accept-Encoding") String encoding, 
@RequestHeader ("Keep-Alive") long keepAlive) { 
EE ive 


若 注解 的 目标 方法 参数 不 是 string 类 型 ， 则 类 型 转换 会 自动 进行 。" 方 法 参数 与 类 型 转换 "一 
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如 果 @RequestHeader 注解 应 用 在 Map<String, String> ` MultiValueMap<String, 
String> 或 HttpHeaders 类 型 的 参数 上 ， 那 么 所 有 的 请 求 头 属性 值 都 会 被 境 充 到 map 中 。 


Spring 内 置 支持 将 一 个 去 号 分 隔 的 字符 串 〈 或 其 他 类 型 转换 系统 所 能 识别 的 类 型 ) 转换 


成 一 个 String 类 型 的 列表 /集合 。 举 个 例子 ， 一 个 注解 了 @RequestHeader ("accept") 的 方法 
参数 可 以 是 一 个 string 类 型 ， 但 也 可 以 是 string[] 或 List<String> 类 型 的 。 


这 个 注解 可 以 注解 到 处 理 器 方法 上 ， 在 Servlet 环 境 和 Portlet 环 境 都 能 使 用 。 


方法 参数 与 类 型 转换 


从 请 求 参 数 、 路 径 变量 、 请 求 头 属性 或 者 cookie 中 抽取 出 来 的 string 类 型 的 值 ， 可 能 需要 被 
转换 成 其 所 绑 定 的 目标 方法 参数 或 字段 的 类 型 〈 比 如 ， 通 过 @ModelAttribute 将 请 求 参 数 绑 定 
到 方法 参数 上 ) 。 如 果 目 标 类 型 不 是 String ， Spring 会 自动 进行 类 型 转换 。 所 有 的 简单 类 型 
诸如 int、long、Date 都 有 内 置 的 支持 。 如 果 想 进一步 定制 这 个 转换 过 程 ， 你 可 以 通 

过 webDataBinder ( 详 见 "定制 WebDataBinder 的 初始 化 "一 节 ) ， 或 者 为 Formatters 配置 一 
个 FormattingConversionService ( 详 见 8.6 节 "Spring 字 段 格 式 化 "一 节 ) 来 做 到 。 


定制 WebDataBinder 的 初始 化 


如 果 想 通 过 Spring 的 WebDataBinder 在 属性 编辑 器 中 做 请 求 参数 的 绑 定 ， 你 可 以 使 用 在 控制 器 
内 使 用 @InitBinder 注解 的 方法 、 在 注解 了 @ControllerAdvice 的 类 中 使 用 @InitBinder 注解 
的 方法 ， 或 者 提供 一 个 定 制 的 WebBindingInitializer ° 更 多 的 细节 TPT? 请 参考 使 用 

人 @ControllerAdvice 辅 助 控制 器 一 节 。 


数据 绑 定 的 定制 : 使 用 @InitBinder 


使 用 @InitBinder 注解 控制 器 的 方法 ， 你 可 以 直接 在 你 的 控制 器 类 中 定制 应 用 的 数据 绑 
定 。 @InitBinder 用 来 标记 一 些 方法 ， 这 些 方法 会 初始 化 一 个 WebDataBinder 并 用 以 为 处 理 器 
方法 填充 命令 对 象 和 表单 对 象 的 参数 。 


了 命令 /表单 对 象 以 及 相应 的 验证 结果 对 象 ， 这 样 的 " 绑 定 器 初始 化 "方法 能 够 接 
@RequestMapping - 支持 的 所 有 参数 类 型 。“ 绑 定 器 初始 化 "方法 不 能 有 返回 值 ， 因 此 ， 一 般 
将 它们 声明 为 void 返回 类 型 。 特 别 地 ， 

当 webDataBinder 与 WebRequest 或 java.util.Locale 一 起 作为 方法 参数 时 ， 你 可 以 在 代码 中 
注册 上 下 文 相 关 的 编辑 器 


下 面 的 代码 示例 a @InitBinder 来 配置 一 个 CustomerDateEditor ? 后 者 会 对 所 
有 java.util.Date 类 型 的 表单 字段 进行 操作 : 


@Controller 
public class MyFormController { 


@InitBinder 

public void initBinder(WebDataBinder binder) { 
SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd"); 
dateFormat.setLenient(false); 


binder.registerCustomEditor(Date.class, new CustomDateEditor(dateFormat, false 


de 


或 者 ， 你 可 以 使 用 Spring 4.24249 addcustomFormatter 来 指定 Formatter 的 实现 ， 而 非 通 
过 propertyEditor 实例 。 这 在 你 拥有 一 个 需要 Formatter 的 Setup 方 法 ， 并 且 该 方法 位 于 一 个 
共享 的 Formattingconversionservice 中 时 非常 有 用 。 这 样 对 于 控制 器 级 别 的 绑 定 规则 的 定 

制 ， 代 码 更 容易 被 复 用 。 


@Controller 
public class MyFormController { 
@InitBinder 


public void initBinder(WebDataBinder binder) { 
binder .addCustomFormatter(new DateFormatter("yyyy-MM-dd")); 


HE eae 


置 定 制 的 WebBindinglnitializer 


为 了 externalize 数 据 绑 定 的 初始 化 过 程 ， 你 可 以 为 WebBindingInitializer 接口 提供 一 个 自己 
的 实现 ， 在 其 中 你 可 以 为 AnnotationMethodHandlerAdapter 提供 一 个 默认 的 配置 bean， 以 此 来 
履 写 默认 的 配置 


以 下 的 代码 来 自 PetClinic 的 应 用 ， 它 展示 了 为 webBindingInitializer 接口 提供 一 个 自 定 义 实 
现 : org.springframework.samples. reaper web.ClinicBindingInitializer 完整 的 配置 过 程 


后 者 中 配置 了 PetClinic 应 用 中 许多 器 所 需要 的 属性 编辑 器 PropertyEditors 。 


o 


<bean class="org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandl 
erAdapter"> 

<property name="cacheSeconds" value="0"/> 

<property name="webBindingInitializer"> 

<bean class="org.springframework.samples.petclinic.web.ClinicBindingInitialize 

ne 

</property> 
</bean> 


@InitBinder 方法 也 可 以 定义 在 @controlleradvice 注解 的 类 上 ， 这 样 配置 可 以 为 许多 控制 器 
所 共享 。 这 提供 了 除 使 用 WebBindingInitializer 外 的 另外 一 种 方法 。 更 多 细节 请 参考 使 用 
@ControllerAdvice 44 3442 #] &—F o 
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we 是 一 个 组 件 注 解 ， 它 使 得 其 实现 类 能 够 被 classpath 扫 描 自 动 发 现 。 若 应 用 
过 MVC 命 令 空间 或 MVC Java 编 程 方式 配置 ， 那 么 该 特性 默认 是 自动 开启 的 。 


注解 @controlleradvice 的 类 可 以 拥 
有 @ExceptionHandler ` @InitBinder 或 @ModelAttribute 注解 的 方法 ， 并 且 这 些 方 法 会 被 应 
用 至 控制 器 类 层次 ?? 的 所 有 @RequestMapping 方法 上 。 


你 也 可 以 通 过 @ControllerAdvice 的 属 ， 隆 来 指 定 其 只 对 一 个 子 集 的 控制 器 生效 


// Target all Controllers annotated with @RestController 
@ControllerAdvice(annotations = RestController.class) 
public class AnnotationAdvice {} 


// Target all Controllers within specific packages 
@ControllerAdvice("org.example.controllers") 


public class BasePackageAdvice {} 


// Target all Controllers assignable to specific classes 
@ControllerAdvice(assignableTypes = {ControllerInterface.class, AbstractController.cla 


ss}) 


public class AssignableTypesAdvice {} 


更 多 的 细节 ， 请 查阅 @controllerAdvice 的 文档 。 


下 面 两 节 ， 还 看 不 太 懂 ， 待 译 。 


Jackson Serialization View Support 


It can sometimes be useful to filter contextually the object that will be serialized to the HTTP 
response body. In order to provide such capability, Spring MVC has built-in support for 
rendering with Jackson's Serialization Views. 


To use it with an @ResponseBody controller method or controller methods that return 
ResponseEntity , Simply add the @Jsonview annotation with a class argument specifying the 
view Class or interface to be used: 


_@RestController_ 
public class UserController { 


_@RequestMapping(path = "/user", method = RequestMethod.GET)_ 
_@JsonView(User .WithoutPasswordView.class)_ 
public User getUser() { 

return new User("eric", "7!jd#h23"); 


public class User { 


public interface WithoutPasswordView {}; 
public interface WithPasswordView extends WithoutPasswordView {}; 


private String username; 
private String password; 


public User() { 
} 


public User(String username, String password) { 
this.username = username; 
this.password = password; 


_@JsonView(WithoutPasswordView.class)_ 
public String getUsername() { 
return this.username; 


_@JsonView(WithPasswordView.class)_ 
public String getPassword() { 
return this.password; 


Note 


Note that despite @jsonview allowing for more than one class to be specified, the use ona 
controller method is only supported with exactly one class argument. Consider the use of a 
composite interface if you need to enable multiple views. 


For controllers relying on view resolution, simply add the serialization view class to the 


model: 


_@Controller_ 
public class UserController extends AbstractController { 


_@RequestMapping(path = "/user", method = RequestMethod.GET)_ 

public String getUser(Model model) { 
model.addAttribute("user", new User("eric", "7!jd#h23")); 
model.addAttribute(JsonView.class.getName(), User.WithoutPasswordView.class); 


return "userView"; 


Jackson JSONP Support 


In order to enable JSONP support for @ResponseBody and ResponseEntity methods, declare 
an @ControllerAdvice bean that extends AbstractJsonpResponseBodyAdvice as shown below 
where the constructor argument indicates the JSONP query parameter name(s): 


_@ControllerAdvice_ 
public class JsonpAdvice extends AbstractJsonpResponseBodyAdvice { 


public JsonpAdvice() { 
super ("callback"); 


For controllers relying on view resolution, JSONP is automatically enabled when the request 
has a query parameter named jsonp or callback . Those names can be customized 


through jsonpParameterNames property. 


21.3.4 异步 请 求 的 处 理 


Spring MVC 3.2 开 始 引 入 了 基于 Servlet 3 的 异步 请 求 处 理 。 相 比 以 前 ， 控 制 器 方法 已 经 不 一 
定 需要 返回 一 个 值 ， 而 是 可 以 返回 一 个 java.util.concurrent.Callable 的 对 象 并 通过 Spring 
MVC 所 管理 的 线程 来 产生 返回 值 。 与 此 同时 ，Servlet 容 器 的 主线 程 则 可 以 退出 并 释放 其 资源 
了 ， 同 时 也 允许 容器 去 处 理 其 他 的 请 求 。 通 过 一 个 TaskExecutor ，Spring MVC 可 以 在 另外 的 
线程 中 调用 callable 。 当 callable 返回 时 ， 请 求 再 携带 callable 返回 的 值 ， 再 次 被 分 配 到 
Servlet 容 器 中 恢复 处 理 流 程 。 以 下 代码 给 出 了 一 个 这 样 的 控制 器 方法 作为 例子 : 


@RequestMapping(method=RequestMethod .POST) 
public Callable<String> processUpload(final MultipartFile file) { 


return new Callable<String>() { 
public String call() throws Exception { 
Le 
return "someView"; 


另 一 个 选择 ， 是 让 控制 器 方法 返回 一 个 DeferredResult 的 实例 。 这 种 场景 下 ， 返 回 值 可 以 由 
任何 一 个 线程 产生 ， 也 包括 那些 不 是 由 Spring MVC 管 理 的 线程 。 举 个 例子 ， 返 回 值 可 能 是 为 
了 响应 某 些 外 部 事件 所 产生 的 ， 比 如 一 条 JMS 的 消息 ， 一 个 计划 任务 ， 等 等 。 以 下 代码 给 
了 一 个 这 样 的 控制 器 作为 例子 : 


@RequestMapping("/quotes") 

@ResponseBody 

public DeferredResult<String> quotes() { 
DeferredResult<String> deferredResult = new DeferredResult<String>(); 
// Save the deferredResult somewhere.. 
return deferredResult; 


// In some other thread... 
deferredResult.setResult (data) ; 


ho R Xt Serviet 3.0 的 异步 请 求 处 理 特性 没有 了 解 ， 理 解 这 个 特性 可 能 会 有 点 困难 。 因 此 ， 阅 读 
一 下 前 者 的 文档 将 会 很 有 帮助 。 以 下 给 出 了 这 个 机 制 运作 背后 的 一 些 原 理 : 


bd 一 个 servlet 请 求 ServletRequest 可 以 通过 调用 request.startAsync() 方法 而 进入 异步 模 
式 。 这 样 做 的 主要 结果 就 是 该 servlet 以 及 所 有 的 过 滤器 都 可 以 结束 ， 但 其 响应 
(response) 会 留待 异步 处 理 结束 后 再 返回 


e 调用 request.startAsync() 方法 会 返回 一 个 AsyncContext 对 象 ， 可 用 它 对 异步 处 理 进 
进一步 的 控制 和 操作 。 比 如 说 它 也 提供 了 一 个 与 转向 很 相似 的 dispatch 方 
法 ， 只 不 过 它 允 许 应 用 恢复 Servlet 容 器 的 请 求 处 理 进 

° ee 提供 了 获取 当前 DispatherType ， 后 者 可 以 用 来 区 别 当 前 处 理 的 是 

原始 请 求 、 弄 步 分 发 请 求 、 转 向 ， 或 是 其 他 类 型 的 请 求 分 发 类 型 。 


有 了 上 面 的 知识 ， 下 面 可 以 来 看 一 下 callable 的 异步 请 求 被 处 理 时 所 依次 发 生 的 事件 : 


e 控制 器 先 返回 一 个 callable HR 

。 Spring MVC 开 始 进行 异步 处 理 ， 并 把 该 callable 对 象 提 交 给 另 一 个 独立 线程 的 执行 
器 TaskExecutor 处 理 

© DispatcherServlet 和 所 有 过 滤器 都 退出 Servlet 容 容 器 线程 但 此 时 方法 的 响应 对 BM; RA 
回 

e Ccallable 对 RRR 生 一 个 返回 结果 ， 此 时 Spring MVC 会 重新 把 请 求 分 站 派 回 Servlet 容 
器 ， 恢 复 处 理 

e DispatcherServlet 再 次 被 调用 ， 恢 复 对 callable 异步 处 理 所 返 回 结果 的 处 理 


对 DeferredResult 异步 请 求 的 处 理 顺 序 也 非常 类 似 ， 区 别 仅 在 于 应 用 可 以 通过 任何 线程 来 计 
算 返 回 一 个 结果 : 


e 控制 器 先 返 回 一 个 DeferredResult 对 象 ， 并 把 它 存 取 在 内 存 〈 队 列 或 列表 等 ) 中 以 便 存 
取 

© Spring MVC 开 始 进行 异步 处 理 

© Dispatcherservlet 和 所 有 过 滤器 都 退出 Servlet 容 器 线程 ， 但 此 时 方法 的 响应 对 象 仍 未 返 
可 

e 由 处 理 该 请 求 的 线程 对 peferredResult 进行 设 值 ， 然 后 Spring MVC 会 重新 把 请 求 分 派 回 
Servlet 容 器 ， 恢 复 处 理 

e DispatcherServlet 再 次 被 调用 ， 恢 复 对 该 异步 返回 结果 的 处 理 


a 
， 你 可 以 从 这 个 系列 的 博客 中 了 解 更 多 信息 。 


异步 请 求 的 异常 处 理 


若 控制 器 返回 的 callable 在 执行 过 程 中 抛 出 了 异常 ， 又 会 发 生 什 么 事情 ? 简单 来 说 ， 这 与 一 
轴 的 控制 器 方法 抛 出 异常 是 一 样 的 。 它 会 被 正常 的 异常 处 理 流程 捕获 处 理 。 更 具体 地 说 呢 ， 

4 callable 抛 出 异常 时 ，Spring MVC 会 把 一 个 Exception 对 象 分 派 给 Servlet 容 器 进行 处 理 ， 
而 不 是 正常 返回 方法 的 返回 值 ， 然 后 容器 恢复 对 此 异步 请 求 异 常 的 处 理 。 若 方法 返回 的 是 一 
个 DeferredResult 对 有 象 ， 你 可 以 选择 调 Exception 实例 的 setResult 方法 还 

是 setErrorResult 方法 。 


= 鹤 异 步 请 求 


处 理 器 拦截 器 HandlerInterceptor 可 以 实现 AsyncHandlerInterceptor 接口 拦截 异步 请 求 
为 在 异步 请 求 开 始 时 ， 被 调用 的 回调 方法 是 该 接口 的 afterconcurrentHandlingstarted 方法 ， 
而 非 一 般 的 postHandle 和 afterCompletion 方法 。 


如 果 需 要 与 异步 请 求 处 理 的 生命 流程 有 更 深入 的 集成 ， 比 如 需要 处 理 timeout 的 事件 等 ， 

则 HandlerInterceptor 需要 注册 一 

个 CallableProcessingInterceptor 或 DeferredResultProcessingInterceptor 拦截 器 。 具 体 的 细 
节 可 以 参考 AsyncHandlerInterceptor 类 的 Java 文 档 。 


DeferredResult 类 还 提供 了 onTimeout (Runnable) 和 onCompletion (Runnable) 等 方法 ， 具体 的 
细节 可 以 参考 DeferredResult 类 的 Java 文 档 。 


callable 需要 请 求 过 期 (timeout) 和 完成 后 的 拦截 时 ， 可 以 把 它 包装 在 一 个 webAsyncTask 实例 
中 ， 后 者 提供 了 相关 的 支持 。 


HTTP streaming( 不 知道 怎么 翻 ) 


如 前 所 述 ， 控 制 器 可 以 使 用 DeferredResult 或 callable 对 象 来 异步 地 计算 其 返回 值 ， 这 可 以 
用 于 实现 一 些 有 用 的 技术 ， 比 如 long polling 技 术 ， 让 服务 器 可 以 尽 可 能 快 地 向 客户 端 推送 事 
件 。 


如 果 你 想 在 一 个 HTTP 响 应 中 同时 推送 多 个 事件 ， 怎 么 办 ? ee 已 经 存在 ， 与 "Long 
Polling" 相 关 ， 叫 "HTTP Streaming" ° Spring een ss 你 可 以 通 ae eae 
个 ResponseBodyEmitter 类 型 对 象 来 实现 ， 该 对 象 可 被 用 于 发 送 多 个 对 象 。 通 常 我 们 所 使 用 
的 @ResponseBody 只 能 返回 一 个 对 象 ， 它 是 通过 HttpMessageConverter eee 8 


下 面 是 一 个 实现 该 技术 的 例子 


@RequestMapping("/events") 

public ResponseBodyEmitter handle() { 
ResponseBodyEmitter emitter = new ResponseBodyEmitter(); 
// Save the emitter somewhere.. 


return emitter; 
// In some other thread 
emitter.send("Hello once"); 


// and again later on 


emitter.send("Hello again"); 


// and done at some point 


emitter.complete(); 


ResponseBodyEmitter 也 可 以 被 放 到 ResponseEntity 体 里 面 使 用 ， 这 可 以 对 响应 状态 和 响应 头 
做 一 些 定制 。 


Note that ResponseBodyEmitter can also be used as the body ina ResponseEntity in order 
to customize the status and headers of the response. 


使 用 “服务 器 端 事件 推送 ”的 HTTP Streaming 


SseEmitter 是 ResponseBodyEmitter 的 一 个 子 类 ， 提 供 了 对 服务 器 端 事件 推送 的 技术 的 支持 所 
服务 器 端 事 件 推送 其 实 只 是 一 种 HTTP Streaming 的 类 似 实现 ， 只 不 过 它 服务 器 端 所 推送 的 事 
件 遵循 了 W3C Server-Sent Events 规 范 中 定义 的 事件 格式 。 


“服务 器 端 事件 推送 "技术 正如 其 名 ， 是 用 于 由 服务 器 端 向 客户 端 进行 的 事件 推送 。 这 在 Spring 
MVC 中 很 容易 做 到 ， 只 需要 方法 返回 一 个 sseEmitter 类 型 的 对 象 即 可 。 


需要 注意 的 是 ，lnternet Explorer 并 不 支持 这 项 服务 器 端 事件 推送 的 技术 。 另 外 ， 对 于 更 大 型 
的 web 应 用 及 更 精致 的 消息 传输 场景 一 “比如 在 线 游 戏 、 在 线 协 作 、 人 金融 应 用 等 一 “来 说 ， 使 
用 Spring 的 WebSocket (包含 SockJS 风 格 的 实时 WebSocket) 更 成 熟 一 些 ， 因 为 它 支持 的 浏 
览 器 范围 非常 广 (包括 IE) ， 并 且 ， 对 于 一 个 以 消息 为 中 心 的 架构 中 ， 它 为 服务 器 端 -客户 端 
间 的 事件 发 布 -订阅 模型 的 交互 提供 了 更 高 层级 的 消息 模式 (messaging patterns) 的 支持 。 





直接 写 回 输出 流 OutputStream 的 HTTP Streaming 


SDR A 也 允许 通过 HttpMessageConverter 向 响应 体 中 支持 写 事件 对 象 。 这 可 能 

最 常见 的 情形 ， 比 如 写 返 回 的 JSON 数 据 的 时 候 。 但 有 时 ， 跳 过 消息 转换 的 阶段 ， 直 接 把 数 
eee 出 流 OutputStream 可 能 更 有 效 ， 比 如 文件 下 载 这 样 的 场景 。 这 可 以 通过 返回 
一 个 streamingResponseBody 类 型 的 对 象 来 实现 。 


以 下 是 一 个 实现 的 例子 


@RequestMapping("/download" ) 
public StreamingResponseBody handle() { 
return new StreamingResponseBody() { 
@Override 
public void writeTo(OutputStream outputStream) throws IOException { 
/AA Write: 
} 
}; 


ResponseBodyEmitter 也 可 以 被 放 到 ResponseEntity 体 里 面 使 用 ， 这 可 以 对 响应 状态 和 响应 头 
做 一 些 定制 。 


异步 请 求 处 理 的 相关 配置 


Servlet 容 器 配置 
对 于 那些 使 用 web.xml 配置 文件 的 应 用 ， 请 确保 web.xml 的 版 本 更 新 到 3.0 : 


<web-app xmlns="http://java.sun.com/xml/ns/javaee" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance http://java.sun.com/xml/ 
ns/javaee 


http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" 
version="3.0"> 


</web-app> 


异步 请 求 必 须 在 web.xml 将 dispatcherServlet 下 的 子 元 素 <async-supported>true</async- 
Supported> 设置 为 true 2 此 外 所 有 可 能 参与 异步 请 求 处 理 的 过 滤器 Filter 都 必须 配置 为 支 
持 ASYNC 类 型 的 请 求 分 派 。 在 Spring 框 架 中 为 过 滤器 启用 支持 ASYNC 类 型 的 请 求 分 派 应 是 安 
全 的 ， 因 为 这 些 过 滤器 一 般 都 继承 了 基 类 onceperRequestFilter ， 后 者 在 运行 时 会 检查 该 过 滤 
器 是 否 需要 参与 到 异步 分 派 的 请 求 处 理 中 。 


以 下 是 一 个 例子 ， 展 示 了 web.xml 的 配置 : 


<web-app xmlns="http://java.sun.com/xml/ns/javaee" 
xmlns:xsi="http://www.w3.0rg/2001/XMLSchema-instance" 
xsi:schemaLocation=" 
http://java.sun.com/xml/ns/javaee 


http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" 
version="3.0"> 


<filter> 


<filter-name>Spring OpenEntityManagerInViewFilter</filter-name> 
<filter-class>org.springframework.~.OpenEntityManagerInViewFilter</filter- 
class> 


<async-supported>true</async - supported> 
</filter> 


<filter -mapping> 
<filter-name>Spring OpenEntityManagerInViewFilter</filter -name> 
<url-pattern>/*</url-pattern> 
<dispatcher>REQUEST</dispatcher> 
<dispatcher>ASYNC</dispatcher> 
</filter-mapping> 


</web-app> 


如 果 应 用 使 用 的 是 Servlet 3 规范 基于 Java 编 程 的 配置 方式 ， 比 如 通 

过 WebApplicationInitializer ， 那 么 你 也 需要 设置 "asyncSupported" 标 志和 ASYNC 分 派 类 型 
的 支持 ， 就 像 你 在 web.xml 中 所 配置 的 一 样 。 你 可 以 考虑 直接 继 

承 AbstractDispatcherServletInitializer 或 ai a e a a 
lizer 来 简化 配置 ， 它 们 都 自动 地 为 你 设置 了 这 些 配 置 项 ， 并 使 得 注册 Filter 过 滤器 实例 变 
得 非常 简单 。 


Spring MVC 配 置 


MVC Java 编 程 配置 和 MVC 命 名 空间 配置 方式 都 提供 了 配置 异步 请 求 处 理 支 持 的 选 
择 。 WebMvcConfigurer 提供 了 configureAsyncSupport 方法 ， 而 <mvc:annotation-driven> 有 一 


个 子 元 素 <async-support> ， 它 们 都 用 以 为 此 提供 支持 。 


这 些 配置 允许 你 覆 写 异步 请 求 默认 的 超时 时 间 ， 在 未 显 式 设置 时 ， 它 们 的 值 与 所 依赖 的 
Servlet 容 器 是 相关 的 (上 比如，Tomcat 设 置 的 超时 时 间 是 10 秒 ) 。 你 也 可 以 配置 用 于 执行 控制 
器 返回 值 callable 的 执行 器 AsyncTaskExecutor 。Spring 强 烈 推 荐 你 配置 这 个 选项 ， 因 为 
Spring MVC 默 认 使 用 的 是 普通 的 执行 器 SimpleAsyncTaskExecutor ° MVC Java 编 程 配置 及 
MVC 命 名 空间 配置 的 方式 都 允许 你 注册 自己 


的 CallableProcessingInterceptor 和 DeferredResultProcessingInterceptor 拦截 器 实例 。 


若 你 需要 为 特定 的 DeferredResult 履 写 默认 的 超时 时 间 ， 你 可 以 选用 合适 的 构造 方法 来 实 

现 。 类 似 ， 对 于 callable 返回 ， 你 可 以 把 它 包 装 在 一 个 WebAsyncTask 对 象 中 ， 并 使 用 合适 的 
构造 方法 定义 超时 时 间 。 webAsyncTask 类 的 构造 方法 同时 也 能 接受 一 个 任务 执行 

器 AsyncTaskExecutor 类 型 的 参数 S 


fi 


’ 


21.3.5 42 Hl A MIX 


spring-test 模块 对 测试 控制 器 @controller 提供 了 最 原生 的 支持 。 详 见 14.6 "Spring MVC 测 


试 框架 "一 节 。 


21.4 232 FRA (Handler Mappings) 


在 Spring 的 上 个 版 本 中 ， 用 户 需要 在 web 应 用 的 上 下 文中 定义 一 个 或 多 个 

的 HandlerMapping bean， 用 以 将 进入 容器 的 web 请 求 映 射 到 合适 的 处 理 器 方法 上 。 人 允许 在 控 
制 器 上 添加 注解 后 2 通常 你 就 不 必 这 么 做 了 ， 因 为 RequestMappingHandlerMapping 类 会 自动 查 
找 所 有 注解 了 @RequestMapping 的 @controller 控制 器 bean。 同 时 也 请 知道 ， 所 有 继承 

É AbstractHandlerMapping 的 处 理 器 方法 映射 HandlerMapping 类 都 拥有 下 列 的 属性 ， 你 可 以 

对 它们 进行 定制 : 


e 一 个 interceptors 列表 ， 指 示 了 应 用 其 上 的 一 个 拦截 器 列表 。 处 理 器 方法 拦截 器 会 在 
21.4.1 小 节 使 用 Handlerlnterceptor 拦 截 请 求 中 讨论 。 

e defaultHandler ， 生 效 的 默认 处 理 器 ，when this handler mapping does not result in a 
matching handler. 

e order ， 根 据 order (I org.springframework.core.Ordered 接口 ) 属性 的 值 ， Spring 会 对 
上 下 文 可 用 的 所 有 处 理 器 映射 进行 排序 ， 并 应 用 第 一 个 匹配 成 功 的 处 理 器 

e alwaysUseFullPath (总 是 使 用 完整 路 径 ) 。 若 设置 为 true ，Spring 将 在 当前 Servlet 上 
下 文中 总 是 使 用 完整 路 径 来 查找 合适 的 处 理 器 。 若 设置 为 false (默认 就 为 false ) ， 
则 使 用 当前 Servlet 的 mapping 路 径 。 举 个 例子 ， 若 一 个 Servlet 的 mapping 路 径 
是 /testing/* ? 并 且 alwaysUseFullPath 属性 被 设置 为 true ， 此 时 用 于 查找 处 理 器 的 路 
径 将 是 /testing/viewPage.html ; 而 若 alwaysUseFullPath 属性 的 值 为 false ， 则 此 时 查 
找 路 径 是 /viewPage.html 

e urlpecode ， 默 认 设 置 为 true (也 是 Spring 2.5 的 默认 设置 ) 。 若 你 需要 比较 加 密 过 的 
路 径 ， 则 把 此 标志 设 为 false 。 需 要 注意 的 是 ， HttpServletRequest 永远 以 未 加 密 的 方 
式 存 储 Servlet 路 径 。 此 时 ， 该 路 径 将 无 法 匹配 到 加 密 过 的 路 径 


下 面 的 代码 展示 了 配置 一 个 拦截 器 的 方法 : 


<beans> 
<bean id="handlerMapping" class="org.springframework.web.servlet.mvc.method.annota 
tion.RequestMappingHandlerMapping"> 
<property name="interceptors"> 
<bean class="example.MyInterceptor"/> 
</property> 
</bean> 


<beans> 


21.4.1 使 用 Handlerinterceptor 拦 截 请 求 


Spring 的 处 理 器 映射 机 制 包含 了 处 理 器 拦截 器 。 拦 截 器 在 你 需要 为 特定 类 型 的 请 求 应 用 一 些 功 
能 时 可 能 很 有 用 ， 比 如 ， 检 查 用 户 身份 等 。 


处 理 器 映射 处 理 过程 配 置 的 拦截 器 ， 必 须 实现 org.springframework.web.servlet 包 下 的 
HandlerInterceptor 接口 。 这 个 接口 定义 了 三 个 方法 : preHandle(..) > CERMAK RIA 
行 之 前 会 被 执行 ; postHandle(..) ， 它 在 处 理 器 执行 完毕 以 后 被 执行 ; 
afterCompletion(..) ? 它 在 整个 请 求 处 理 完 成 之 后 被 执行 。 这 三 个 方法 为 各 种 类 型 的 前 处 
理 和 后 处 理 需 求 提供 了 足够 的 灵活 性 。 


preHandle(..) 方法 返回 一 个 boolean 值 。 你 可 以 通过 这 个 方法 来 决定 是 否 继续 执行 处 理 链 中 
的 部 件 。 当 方法 返回 true 时 ， 处 理 器 链 会 继续 执行 ; 若 方 法 返回 false ， 
DispatcherServlet 即 认为 拦截 器 自身 已 经 完成 了 对 请 求 的 处 理 (比如 说 ， 已 经 演 染 了 一 个 合 
适 的 视图 ) ， 那 么 其 余 的 拦截 器 以 及 执行 链 中 的 其 他 处 理 器 就 不 会 再 被 执行 了 。 


拦截 器 可 以 通过 interceptors 属性 来 配置 ， 该 选项 在 所 有 继承 了 AbstractHandlerMapping 的 
处 理 器 映射 类 HandlerMapping 都 提供 了 配置 的 接口 。 如 下 面 代 码 样 例 所 示 : 


<beans> 
<bean id="handlerMapping" class="org.springframework.web.servlet.mvc.method.annota 
tion.RequestMappingHandlerMapping"> 
<property name="interceptors"> 
<list> 
<ref bean="officeHoursInterceptor"/> 
</list> 
</property> 
</bean> 


<bean id="officeHoursInterceptor" class="samples.TimeBasedAccessInterceptor"> 
<property name="openingTime" value="9"/> 
<property name="closingTime" value="18"/> 

</bean> 


<beans> 


package samples; 
public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter { 


private int openingTime; 
private int closingTime; 


public void setOpeningTime(int openingTime) { 
this.openingTime = openingTime; 


public void setClosingTime(int closingTime) { 
this.closingTime = closingTime; 


public boolean preHandle(HttpServletRequest request, HttpServletResponse response, 
Object handler) throws Exception { 
Calendar cal = Calendar.getInstance(); 
int hour = cal.get(HOUR_OF_DAY); 
if (openingTime <= hour && hour < closingTime) { 
return true; 


} 


response. sendRedirect ("http://host.com/outsideOfficeHours.html"); 
return false; 


在 上 面 的 例子 中 ， 所 有 被 此 处 理 器 处 理 的 请 求 都 会 被 TimeBasedAccessinterceptor 拦截 器 拦 
截 。 如 果 当 前 时 间 在 工作 时 间 以 外 ， 那 么 用 户 就 会 被 重 定向 到 一 个 HTML 文 件 提示 用 户 ， 比 如 
显示 “你 只 有 在 工作 时 间 才 可 以 访问 本 网 站 "之 类 的 信息 。 


使 用 RequestMappingHandlerMapping 时 ， 实 际 的 处 理 器 是 一 个 处 理 器 方 
法 HandlerMethod 的 实例 ， 它 标识 了 一 个 将 被 用 于 处 理 该 请 求 的 控制 器 方法 。 


你 所 见 ，Spring 的 拦截 器 适配器 HandlerInterceptorAdapter 让 继承 HandlerInterceptor 接 
de 简单 了 。 


上 面 的 例子 中 ， 所 有 控制 器 方法 处 理 的 请 求 都 会 被 配置 的 拦截 器 先 拦截 到 。 如 果 你 想 进 
一 步 缩小 拦截 的 URL 范 围 ， 你 可 以 通过 MVC 命 名 空间 或 MVC Java 编 程 的 方式 来 配置 
或 者 ， 声 明 一 个 MappedInterceptor 类 型 的 bean 实 例 来 处 理 。 上 有 具体 请 见 21.16.1 启用 
MVC Java 编 程 配置 或 MVC 命 名 空间 配置 一 小 节 。 


需要 注意 的 是 ，HandlerInterceptor 的 后 拦截 postHandle 方法 不 一 定 总 是 适用 于 注解 

了 @ResponseBody 或 ResponseEntity cans 这 些 场景 中 ， HttpMessageconverter 会 在 拦截 器 
的 postHandle 方法 被 调 之 前 就 把 信息 写 回 响应 中 。 这 样 拦截 器 就 无 法 再 改变 响应 了 ， 比 如 要 
增加 一 个 响应 头 之 类 的 。 如 果 有 这 eee ， 请 让 你 的 应 用 实现 ResponseBodyAdvice 接口 ， 并 

将 其 定义 为 一 个 @controllerAdvice bean 或 直接 在 RequestMappingHandlerMapping 中 配置 。 


使 用 Handlerlnterceptor 拦 截 请 求 
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21.5 视图 解析 


所 有 web 应 用 的 MVC 框 架 都 提供 了 视图 相关 的 支持 。Spring 提 供 了 一 些 视图 解析 器 ， 它 们 让 

你 能 够 在 浏览 器 中 渔业 模型 ， 并 支持 你 自由 选用 适合 的 视图 技术 而 不 必 与 框架 绑 定 到 一 起 。 
Spring 原生 支持 JSP 视 图 技术 、Velocity 模 板 技术 和 XSLT 视 图 等 。 你 可 以 阅读 文档 的 第 22 章 

视图 技术 一 章 ， 里 面 讨 论 了 如 何 集成 并 使 用 许多 独立 的 视图 技术 。 


有 两 个 接口 在 Spring 处 理 视图 相关 事宜 时 至 关 重 要 ， 分 别 是 视图 解析 器 接口 viewResolver 和 
视图 接口 本 身 view 。 视 图 解析 器 viewResolver 负责 ea 与 实际 视图 之 间 的 映射 关 
系 。 视 图 接口 view 负责 准备 请 求 ， 并 将 请 求 的 泻 染 交 给 某 种 具体 的 视图 技术 实现 。 


21.5.1 使 用 ViewResolver 接 口 解 析 视 图 


正如 在 21.3 控制 器 的 实现 一 节 中 所 讨论 的 ，Spring MVC 中 所 有 控制 器 的 处 理 器 方法 都 必须 返 
回 一 个 逻辑 视图 的 名 字 ， 无 论 是 显 式 返 回 (比如 返回 一 个 String ` View 或 

者 Modelandview ) 还 是 隐 式 返回 (比如 基于 约定 的 返回 ) 。Spring 中 的 视图 由 一 个 视图 名 标 
识 ， 并 由 视图 解析 器 来 泻 染 。Spring 有 非常 多 内 置 的 视图 解析 器 。 下 表 列 出 了 大 部 分 ， 表 后 也 
给 出 了 一 些 例子 。 


表 21.3 视图 解析 器 


视图 解析 器 首 述 
一 个 抽象 的 视图 解析 器 类 ， 提 供 了 缓存 视图 的 功能 。 
AbstractCachingViewResolver 通常 视图 在 能 够 被 使 用 之 前 需要 经 过 准备 。 继 承 这 个 


基 类 的 视图 解析 器 即 可 以 获得 缓存 视 图 的 能 力 。 


视图 解析 器 接口 viewResolver 的 一 个 实现 ， 该 类 接 
受 一 个 XML 格式 的 配置 文件 。 该 XML 文件 必须 与 
Spring XML 的 bean 工 厂 有 相同 的 DTD。 黑 认 的 配置 
文件 名 是 /WEB-INF/views.xml ° 


Xm1ViewResolver 


视图 解析 器 接口 viewResolver 的 一 个 实现 ， 采 用 
bundle 根 路 径 所 指定 的 ResourceBundle 中 的 bean 定 

ResourceBundleViewResolver 义 作 为 配置 。 一 般 bundle 都 定义 在 classpath 路 径 下 
的 一 个 配置 文件 中 。 默 认 的 配置 文件 名 


为 views. properties ° 


ViewResolver 接口 的 一 个 简单 实现 。 它 直接 使 用 
URL 来 解析 到 逻辑 视图 名 ， 除 此 之 外 不 需要 其 他 任何 

UrlBasedViewResolver 显 式 的 映射 声明 。 如 果 你 的 逻辑 视图 名 与 你 丨 正 的 视 
图 资源 名 是 直接 对 应 的 ， 那 么 这 种 直接 解析 的 方式 就 
很 方便 ， 不 需要 你 再 指定 额外 的 映射 。 


UrlBasedViewResolver 的 一 个 好 用 的 子 类 。 它 支 持 内 
部 资源 视图 (具体 来 说 ，Servlet 和 JSP) ` ARB 
如 Jstlview 和 Tilesview 等 类 的 子 类 。You can 
specify the view class for all views generated by this 
resolver by using setViewClass(..) 。 更 多 的 细节 ， 
请 见 UrlBasedViewResolver 类 的 java 文 档 。 


InternalResourceViewResolver 


re ) UrlBasedViewResolver 下 的 实用 子 类 ， 支 持 Velocity 
Valee EA ENSSO VE 视图 velocityview (Velocity 模 板 ) 和 FreeMarker 视 
FreeMarkerViewResolver § are 5 有 
图 Freemarkerview 以 及 它们 对 应 子 类 。 


视图 解析 器 接口 viewResolver 的 一 个 实现 ， 它 会 根 
据 所 请 求 的 文件 名 或 请 求 的 Accept 头 来 解析 一 个 视 
图 。 更 多 细节 请 见 21.5.4 内 容 协商 视图 解析 

器 "ContentNegotiatingViewResolver" 一 小 节 。 


ContentNegotiatingViewResolver 


我 们 可 以 举 个 例子 ， 假 设 这 里 使 用 的 是 JSP 视 图 技术 ， 那 么 我 们 可 以 使 用 一 个 基于 URL 的 视图 
解析 器 UrlBasedviewResolver 。 这 个 视图 解析 器 会 将 URL 解 析 成 一 个 视图 名 ， 并 将 请 求 转交 给 


请 求 分 发 器 来 进行 视图 泻 染 。 


<bean id="viewResolver" class="org.springframework.web.servlet.view.UrlBasedViewResolv 


airis 
<property name="viewClass" value="org.springframework.web.servlet.view.JstlView"/> 


<property name="prefix" value="/WEB-INF/jsp/"/> 
<property name="suffix" value=".jsp"/> 


</bean> 


若 返回 一 个 test 逻辑 视图 名 ， 那 么 该 视图 解析 器 会 将 请 求 转 发 到 RequestDispatcher ， 后 者 
会 将 请 求 交 给 /WEB-INF/jsp/test.jsp 视图 去 泻 染 。 


如 果 需 要 在 应 用 中 使 用 多 种 不 同 的 视图 技术 ， 你 可 以 使 用 ResourceBundleviewResolver 


<bean id="viewResolver" 
class="org.springframework.web.servlet.view.ResourceBundleViewResolver"> 


<property name="basename" value="views"/> 
<property name="defaultParentView" value="parentView"/> 


</bean> 


ResourceBundleViewResolver 会 检索 由 bundle 根 路 径 下 所 配置 的 ResourceBundle ， 对 于 每 个 视 
图 而 言 ， 其 视图 类 由 [viewname].(class) 属性 的 值 指定 ， 其 视图 Url 由 [viewname].url 属性 的 
值 指定 。 下 一 节 将 详细 讲解 视图 技术 ， 你 可 以 在 那里 找到 更 多 例子 。 你 还 可 以 看 到 ， 视 图 还 
允许 有 基 视 图 ， 即 properties 文 件 中 所 有 视图 都 “继承 ”的 一 个 文件 。 通 过 继承 技术 ， 你 可 以 为 
众多 视图 指定 一 个 默认 的 视图 基 类 。 

AbstractCachingViewResolver 的 子 类 能 够 缓存 已 经 解析 过 的 视图 实例 。 关 闭 缓存 特性 也 

是 可 以 的 ， 只 需要 将 cache 属性 设置 为 false ani “i ， 如 果实 在 需要 在 运行 时 刷新 

某 个 视图 〈 比 如 修改 了 Velocity 模板 时 ) ， 你 可 以 使 用 removeFromcache(String viewName, 


Locale loc) 方法 。 


21.5.2 视图 链 


Spring 支持 同时 使 用 多 个 视图 解析 器 。 因 此 ， 你 可 以 配置 一 个 解析 器 链 ， 并 做 更 多 的 事 比 如 ， 
在 特定 条 件 下 履 写 一 个 视图 等 。 你 可 以 通过 把 多 个 视图 解析 器 设置 到 应 用 上 下 文 (application 
context) 中 的 方式 来 串联 它们 。 如 果 需 要 指定 它们 的 次 序 ， 那 么 设置 order 属性 即 可 。 请 记 
住 ，order 属 性 的 值 越 大 ， 该 视图 解析 器 在 链 中 的 位 置 就 越 靠 后。 


在 下 面 的 代码 例子 中 ， 视 图 解析 器 链 中 包含 了 两 个 解析 器 : 一 个 

是 InternalResourceViewResolver ， 它 总 是 自 动 被 放置 在 解析 器 链 的 最 后 ; 另 一 个 

是 XmlViewResolver ， 它 用 来 指定 Excel 视 图 ° InternalResourceViewResolver 不 支持 Excel 视 
图 。 


<bean id="jspViewResolver" class="org.springframework.web.servlet.view.InternalResourc 
eViewResolver"> 


<property name="viewClass" value="org.springframework.web.servlet.view. JstlView"/> 
<property name="prefix" value="/WEB-INF/jsp/"/> 
<property name="sSuffix" value=".jsp"/> 

</bean> 


<bean id="excelViewResolver" class="org.springframework.web.servlet.view.XmlViewResolv 
C= 

<property name="order" value="1"/> 

<property name="location" value="/WEB-INF/views.xm1"/> 
</bean> 


<!-- in views.xml --> 


<beans> 


<bean name="report" class="org.springframework.example.ReportExcelView"/> 
</beans> 


如 果 一 个 视图 解析 器 不 能 返回 一 个 视图 ， 那 么 Spring 会 继续 检查 上 下 文中 其 他 的 视图 解析 器 。 
此 时 如 果 存 在 其 他 的 解析 器 ，Spring 会 继续 调用 它们 ， 直 到 产生 一 个 视图 返回 为 止 。 如 果 最 后 


所 有 视图 解析 器 都 不 能 返回 一 个 视图 ， Spring 就 抛 出 一 个 ServletException ° 


视图 解析 器 的 接口 清楚 声明 了 ， 一 个 视图 解析 器 是 可 以 返回 null 值 的 ， 这 表示 不 能 找到 任何 合 
适 的 视图 。 并 非 所 有 的 视图 解析 器 都 这 么 做 ， 但 是 也 存在 不 得 不 如 此 的 场景 ， 即 解析 器 确实 
无 法 检测 对 应 的 视图 是 否 存在 。 比 如 ， InternalResourceViewResolver 在 内 部 使 用 

J RequestDispatcher ， 并 且 进 入 分 派 过 程 是 检测 一 个 JSP 视 图 是 否 存在 的 唯一 方法 ， 但 这 个 
过 程 仅 可 能 发 生 唯 一 一 次 。 同 样 的 velocityviewResolver 和 部 分 其 他 的 视图 解析 器 也 存在 这 样 
的 情况 。 具 体 的 请 查阅 某 个 特定 的 视图 解析 器 的 Java 文 档 ， 看 它 是 否 会 report 不 存在 的 视图 。 
因此 ， 如 果 不 把 InternalResourceViewResolver 放置 在 解析 器 链 的 最 后 ， 将 可 能 导致 解析 器 链 
无 法 完全 执行 ， 因 为 InternalResourceViewResolver 永远 都 会 返回 一 个 视图 。 
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21.5.3 视图 重 定向 


如 前 所 述 ， 控 制 器 通常 都 会 返回 一 个 逻辑 视图 名 ， 然 后 视图 解析 器 会 把 它 解 析 到 一 个 具体 的 

视图 技术 上 去 泻 染 。 对 于 一 些 可 以 由 Servlet 或 JSP 引 擎 来 处 理 的 视图 技术 ， 比 如 JSP 等 ， 这 个 

J 党 是 由 InternalResourceViewResolver 和 InternalResourceView 协作 来 完成 的 ， 而 
这 通常 会 调用 Servlet 的 API RequestDispatcher.forward(..) 方法 

或 RequestDispatcher.include(..) 方法 ， 并 发 生 一 次 内 部 的 转发 (forward) 或 引用 

(include) 。 而 对 于 其 他 的 视图 技术 ， 比 如 Velocity、XSLT 等 ， 视 图 本 身 的 内 容 是 直接 被 写 

回响 应 流 中 的 。 


有 时 ， 我 们 想 要 在 视图 泻 染 之 前 ， 先 把 一 个 HTTP 重 定向 请 求 发 送 回 客户 端 。 比 如 ， 当 一 个 控 
制 器 成 功 地 接受 到 了 post 过 来 的 数据 ， 而 响应 仅仅 是 委托 另 一 个 控制 器 来 处 理 (比如 一 次 成 
功 的 表单 提交 ) 时 ， ie o 在 这 种 场景 下 ， 如 果 只 是 简单 地 使 用 内 部 转 


发 ， 那 么 意味 着 下 一 个 控制 能 看 到 这 次 posT 请 ， oe Lame 问 
题 ， 比 如 可 能 会 与 其 他 期 。 此 外 ， 另 一 种 在 泻 染 视 对 请 求 进行 重 定 向 


的 需求 是 ， 防 止 用 户 多 次 提交 ss 。 此 时 若 使 用 重 定向 ， 则 浏 先 发 送 第 一 

个 post 请 求 ; 请 求 被 处 理 后 浏览 器 会 收 到 一 个 重 定向 响应 ， 然 后 浏览 器 直接 被 重 定向 到 一 个 

不 同 的 URL， 最 后 浏览 器 会 使 用 重 定向 响应 中 携带 的 URL 发 起 一 次 GET 请 求 。 因 此 ， 从 浏览 
器 的 角度 看 ， 当 前 所 见 的 post 请 求 的 结果 ， 而 是 一 次 GET 请 求 的 结果 。 这 就 防 

止 了 用 户 因 刷新 等 原因 意外 地 提交 了 多 次 同样 的 数据 。 此 时 刷新 会 重新 GET 一 次 结果 页 ， 而 

不 是 把 同样 的 post 数据 再 发 送 一 遍 


` 


重 定 向 视图 RedirectView 


强制 重 定向 的 一 种 方法 是 ， 在 控制 器 中 创 建 并 返回 一 个 Spring 重 定向 视图 RedirectView 的 实 

例 。 它 会 使 得 DispatcherServlet oe 解析 机 制 ， 因 为 你 已 经 返回 一 个 ( 重 定 
向 ) 视图 给 Dispatcherservlet 了 ， 所 以 它 会 构造 一 个 视图 来 满足 泻 染 的 需求 。 紧 接 

A RedirectView 会 调用 HttpservletResponse.sendRedirect() 方法 ， 发 送 一 个 HTTP 重 定向 响 


We oe 


给 客户 端 浏览 器 。 


如 果 你 决定 返回 Redirectview ， 并 且 这 个 视图 实例 是 由 控制 器 内 部 创 | 建 出 来 的 ， ， 那 我 们 更 推 
荐 在 外 部 配置 重 定向 URL 然 后 注入 到 控制 器 中 来 ， 而 不 是 写 在 控制 器 里 面 。 这 样 它 就 可 以 与 
视图 名 一 起 在 配置 文件 中 配置 。 关 于 如 何 实现 这 个 解 厢 ， 请 参考 重 定向 前 级 


ae 


P o 


redirect: 一 小 





向 重 定 向 目标 传递 数据 


模型 中 的 所 有 属性 默认 都 会 考虑 作为 URI 模 板 变 量 被 添加 到 重 定向 URL 中 。 剩 下 的 其 他 属性 ， 
如 果 是 基本 类 型 或 者 基本 类 型 的 集合 或 数组 ， 那 它们 将 被 自动 添加 到 URL 的 查询 参数 中 去 。 
如 果 model 是 专门 为 该 重 定 向 所 准备 的 ， 那 么 把 所 有 基本 类 型 的 属性 添加 到 查询 参数 中 可 能 是 
我 们 期 望 那个 的 结果 。 但 是 ， 在 包含 注解 的 控制 器 中 ，model 可 能 包含 了 专门 作为 泻 染 用途 的 
属性 (比如 一 个 下 拉 列 表 的 字段 值 等 )。 为 了 避免 把 这 样 的 属性 也 暴露 在 URL 

中 ， @RequestMapping 方法 可 以 声明 一 个 Redirectattributes 类 型 的 方法 参数 ， 用 它 来 指定 专 
门 供 重 定向 视图 Redirectview 取 用 的 属性 。 如 果 重 定向 成 功 发 生 ， 那 

A RedirectAttributes 对 象 中 的 内 容 就 会 被 使 用 ; 否则 则 使 用 模型 model 中 的 数据 。 


RequestMappingHandlerAdapter 提供 了 一 个 "ignoreDefaultModelOnRedirect" 标志 。 它 被 用 来 标 
记 默 认 Model 中 的 属性 永远 不 应 该 被 用 于 控制 器 方法 的 重 定向 中 。 控 制 器 方法 应 该 声明 一 

个 RedirectAttributes 。 如 果 不 声 明 ， 那 就 没有 参数 被 传递 到 重 定向 的 视 

图 RedirectView 中 。 在 MVC 命 名 空间 或 MVC Java 编 程 配置 方式 中 ， 为 了 维持 向 后 的 兼容 

性 ， 这 个 标志 都 仍 被 保持 为 false 。 但 如 果 你 的 应 用 是 一 个 新 的 项 目 ， 那 么 我 们 推荐 把 它 的 
值 设置 成 true ° 


ee we 
式 地 在 Model 或 RedirectAttributes 中 再 添加 属性 。 请 看 下 面 的 例子 


a aie = "/files/{path}", method = RequestMethod. POST) 
public String upload(...) { 

WH ae 

return redirect: files/{pathia; 


另外 一 种 向 重 定向 目标 传递 数据 的 方法 是 通过 闪存 属性 (Flash Attributes) 。 与 其 他 重 定向 
属性 不 同 ，flash 属 性 是 存储 在 HTTP session 中 的 〈 因 此 不 会 出 现在 URL 中 ) 。 更 多 内 容 ， 请 
参考 21.6 使 用 闪存 属性 一 节 。 





重 定 向 前 组 


尽管 使 用 RedirectView KE A Gi ELH 很 好 ， 但 如 果 控 制 器 自 HE 是 需要 创建 一 

个 RedirectView ， 那 无 疑 控制 器 还 是 了 解 重 定向 这 入 一 件 事情 的 发 生 。 这 还 是 有 点 不 尽 完 
> 不 同 范畴 的 耦合 还 是 太 强 。 控 制 器 其 实 不 应 该 去 关心 响应 会 如 何 被 泻 当 。In general it 

should operate only in terms of view names that have been injected into it. 


redirect: 


一 个 特别 的 视图 名 前 前 组 能 完成 这 个 解 耦 > redirect: ° 如 果 返 回 的 视图 名 中 含有 redirect: 前 
级， 那么 UrlBasedViewResolver (及 它 的 所 有 子 类 ) 就 会 接受 到 这 个 信号 ， 意 识 到 这 里 需要 发 
生 重 定向 。 然 后 视图 名 剩 下 的 部 分 会 被 解析 成 重 定向 URL。 


这 种 方式 与 通过 控制 器 返回 一 个 重 定 向 视图 Redirectview 所 达到 的 效果 是 一 样 的 ， 不 过 这 样 
一 来 控制 器 就 可 以 只 专注 于 处 理 并 返回 逻辑 视图 名 了 。 如 果 逻 辑 视图 名 是 这 样 的 形 

Ñ : redirect:/myapp/some/resource ， 他 们 重 定向 路 径 将 以 Servlet 上 下 文 作为 相对 路 径 进行 
查找 ， 而 逻辑 视图 名 如 果 是 这 样 的 形式 > redirect:http://myhost.com/some/arbitrary/path ， 
那么 重 定 向 URL 使 用 的 就 是 绝对 路 径 。 


注意 的 是 ， 如 果 控 制 器 方法 注解 了 @ResponseStatus ° A 注解 设置 的 状态 码 值 会 履 
盖 RedirectView 设置 的 响应 状态 码 值 。 





Ee) Ay 


对 于 最 终 会 被 UrlBasedviewResolver 或 其 子 类 解析 的 视图 名 ， 你 可 以 使 用 一 个 特殊 的 前 

级 : forward: 。 这 会 导致 一 个 internalResourceview 视图 对 象 的 创建 ( 它 最 终 会 调 

用 RequestDispatcher.forward() 方法 ) 2 后 者 会 认为 视图 名 剩 下 的 部 分 是 一 个 URL 。 因此， 
这 个 前 级 在 使 用 InternalResourceViewResolver 和 InternalResourceView 时 并 没有 特别 的 作用 
(比如 对 于 JSP 来 说 ) 。 但 当 你 主要 使 用 的 是 其 他 的 视图 技术 ， 而 又 想 要 强制 把 一 个 资源 转发 

给 Servlet/JSP 引 擎 进行 处 理 时 ， 这 个 前 组 可 能 就 很 有 用 (或 者 ， 你 也 可 能 同时 串联 多 个 视图 

解析 器 ) 。 


forward: 


与 redirect: 前 级 一样 ， 如 果 控 制 器 中 的 视图 名 使 用 了 forward: 前 级 ， 控 制 器 本 身 并 不 会 发 
觉 任 何 异 常 ， 它 关注 的 仍然 只 是 如 何 处 理 响 应 的 问题 。 


21.5.4 内 容 协 商 解 析 器 
ContentNegotiatingViewResolver 


ContentNegotiatingViewResolver 自 己 并 不 会 解析 视图 而 是 委托 给 其 他 的 视图 解析 器 去 处 
JẸ o 


The ContentNegotiatingViewResolver does not resolve views itself but rather delegates to 
other view resolvers, selecting the view that resembles the representation requested by the 
client. Two strategies exist for a client to request a representation from the server: 


e Use a distinct URI for each resource, typically by using a different file extension in the 
URI. For example, the URI <http://ww.example.com/users/fred.pdf> requests a PDF 
representation of the user fred, and <http://www.example.com/users/fred.xml> requests 
an XML representation. 

e Use the same URI for the client to locate the resource, but set the Accept HTTP 
request header to list the media types that it understands. For example, an HTTP 
request for <http://www.example.com/users/fred> with an Accept header set to 

application/pdf requests a PDF representation of the user fred, while 
<http://www.example.com/users/fred> with an Accept header set to text/xml requests 
an XML representation. This strategy is known as content negotiation. 


Note 


One issue with the accept header is that it is impossible to set it in a web browser within 
HTML. For example, in Firefox, it is fixed to: 


Accept: text/html, application/xhtml+xml, application/xml; q=0.9, */*;q=0.8 


For this reason it is common to see the use of a distinct URI for each representation when 
developing browser based web applications. 


To support multiple representations of a resource, Spring provides the 

ContentNegotiatingViewResolver to resolve a view based on the file extension or Accept 
header of the HTTP request. contentNegotiatingviewResolver does not perform the view 
resolution itself but instead delegates to a list of view resolvers that you specify through the 
bean property viewResolvers . 


The contentNegotiatingViewResolver selects an appropriate view to handle the request by 
comparing the request media type(s) with the media type (also Known as Content-Type ) 
supported by the view associated with each of its viewResolvers . The first view in the list 
that has a compatible Content- Type returns the representation to the client. If a compatible 
view cannot be supplied by the viewResolver chain, then the list of views specified through 
the Defaultviews property will be consulted. This latter option is appropriate for singleton 

views that can render an appropriate representation of the current resource regardless of 
the logical view name. The Accept header may include wild cards, for example text/* , in 
which case a view whose Content-Type was text/xml is a compatible match. 


To support custom resolution of a view based on a file extension, use a 
ContentNegotiationManager : see Section 21.16.6, "Content Negotiation”. 


Here is an example configuration of a contentNegotiatingViewResolver : 


<bean class="org.springframework.web.servlet.view.ContentNegotiatingViewResolver"> 
<property name="ViewResolvers"> 
<list>) 
<bean class="org.springframework.web.servlet.view.BeanNameViewResolver"/> 
<bean class="org.springframework.web.servlet.view.InternalResourceViewReso 


lver"> 
<property name="prefix" value="/WEB-INF/jsp/"/> 
<property name="suffix" value=".jsp"/> 
</bean> 
</list> 
</property> 


<property name="defaultViews"> 
<list> 
<bean class="org.springframework.web.servlet.view.json.MappingJackson2Json 
View"/> 
</list> 
</property> 
</bean> 


<bean id="content" class="com.foo.samples.rest.SampleContentAtomView"/> 


The InternalResourceViewResolver handles the translation of view names and JSP pages, 
while the BeanNameViewResolver returns a view based on the name of a bean. (See " 
[Resolving views with the ViewResolver interface](mvc.html 


mvc-viewresolver-resolver "21.5.1 
Resolving views with the ViewResolver 


interface" )" for more details on how Spring looks up and instantiates a view.) In this 
example, the content bean is a class that inherits from AbstractAtomFeedview , which 
returns an Atom RSS feed. For more information on creating an Atom Feed representation, 
see the section Atom Views. 


In the above configuration, if a request is made with an .html extension, the view resolver 
looks for a view that matches the text/html media type. The 

InternalResourceViewResolver provides the matching view for text/html . If the request is 
made with the file extension .atom , the view resolver looks for a view that matches the 

application/atom+xml media type. This view is provided by the BeanNameViewResolver that 
maps to the sampleContentAtomview if the view name returned is content . If the request is 
made with the file extension .json , the MappingJackson2Jsonview instance from the 

DefaultViews list will be selected regardless of the view name. Alternatively, client requests 
can be made without a file extension but with the Accept header set to the preferred media- 
type, and the same resolution of request to views would occur. 


Note 


If *ContentNegotiatingViewResolver's list of ViewResolvers is not configured explicitly, it 
automatically uses any ViewResolvers defined in the application context. 


The corresponding controller code that returns an Atom RSS feed for a URI of the form 
<http://localhost/content.atom> Or <http://localhost/content> With an Accept header of 


application/atom+xml is shown below. 


@Controller 
public class ContentCont1 { 


private List<SampleContent> contentList = new ArrayList<SampleContent>(); 


@RequestMapping(path="/content", method=RequestMethod.GET) 
public ModelAndView getContent() { 
ModelAndView mav = new ModelAndView(); 
mav.setViewName("content"); 
mav.addObject("sampleContentList", contentList); 
return mav; 


21.6 使 用 闪存 属性 FlashAttributes 


Flash 属 性 (flash attributes) 提供 了 一 个 请 求 为 另 一 个 请 求 存储 有 用 属性 的 方法 。 这 在 重 定 
向 的 时 候 最 常 使 用 ， 比 如 常见 的 POST/REDIRECT/GET 模式 。Flash 属 性 会 在 重 定 向 前 被 暂 
时 地 保存 起 来 (通常 是 保存 在 session 中 ) ， 重 定向 后 会 重新 被 下 一 个 请 求 取 用 并 立即 从 原 保 
存 地 移 除 。 


为 支持 flash 属 性 ，Spring MVC 提 供 了 两 个 抽象 。 FlashMap 被 用 来 存储 flash 属 性 ， 而 
用 FlashMapManager 来 存储 、 取 回 、 管 理 FlashMap 的 实例 。 


对 flash 属 性 的 支持 默认 是 启用 的 ， 并 不 需要 显 式 声明 ， 不 过 没 用 到 它 时 它 绝 不 会 主动 地 去 创 
建 HTTP 会 话 (session) 。 对 于 每 个 请 求 ， 框 架 都 会 “ 传 进 " 一 个 FlashMap > BOAT AL 
个 请 求 (如果 有 ) 保存 下 来 的 属性 ; 同时 ， 每 个 请 求 也 会 “输出 ”一 个 FlashMap ， 里 面 保存 了 
要 给 下 个 请 求 使 用 的 属性 。 两 个 FlashMap 实例 在 Spring MVC 应 用 中 的 任何 地 点 都 可 以 通 

过 RequestContextUtils 工具 类 的 静态 方法 取得 。 


控制 器 通常 不 需要 直接 接触 FlashMap ° 一 般 是 通过 @RequestMapping 方法 去 接受 一 

个 RedirectAttributes 类 型 的 参数 ， 然 后 直接 地 往 其 中 添加 flash 属 性 。 通 

过 Redirectattributes 对 象 添加 进去 的 flash 属 性 会 自动 被 填充 到 请 求 的 “输出 ” FlashMap 对 象 
中 去 。 类 似 地 ， 重 定向 后 " 传 进 "的 FlashMap 属性 也 会 自动 被 添加 到 服务 重 定向 URL 的 控制 器 
参数 Model 中 去 。 


匹配 请 求 所 使 用 的 flash 属 性 


flash 属 性 的 概念 在 其 他 许多 的 Web 框 架 中 也 存在 ， 并 且 实 践 证 明 有 时 可 能 会 导致 并 发 上 的 问 
题 。 这 是 因为 从 定义 上 讲 ，flash 属 性 保存 的 时 间 是 到 下 个 请 求 接收 到 之 前 。 问 题 在 于 ，“ 下 一 
个 "请 求 不 一 定 刚好 就 是 你 要 重 定向 到 的 那个 请 求 ， 它 有 可 能 是 其 他 的 异步 请 求 (比如 polling 
请 求 或 者 资源 请 求 等 )。 这 会 导致 flash 属 性 在 到 达 申 正 的 目标 请 求 前 就 被 移 除 了 。 


为 了 减少 这 个 问题 发 生 的 可 能 性 ， 重 定向 视图 RedirectView 会 自动 为 一 个 FlashMap 实例 记录 
其 目 标 重 定向 URL 的 路 径 和 查询 参数 。 然 后 ， 默 认 的 FlashMapManager 会 在 为 请 求 查 找 其 
BAe EH) FlashMap 时 ， 匹 配 这 些 信息 。 


这 并 不 能 完全 解决 重 定向 的 并 发 问题 ， 但 极 大 程度 地 减少 了 这 种 可 能 性 ， 因 为 它 可 以 从 重 定 


向 URL 已 有 的 信息 中 来 做 匹配 。 因 此 ， 一 般 只 有 在 重 定向 的 场景 下 ， 我 们 才 推 荐 使 用 flash 属 
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21.7 URI 构 造 


在 Spring MVC 中 ， 使 用 了 UricomponentsBuilder 和 Uricomponents 两 个 类 来 提供 一 种 构造 和 
加 密 URI 的 机 制 。 


比如 ， 你 可 以 通过 一 个 URI 模 板 字 符 串 来 填充 并 加 密 一 个 URI : 


UriComponents uriComponents = UriComponentsBuilder.fromUriString( 
"http: //example.com/hotels/{hotel}/bookings/{booking}").build(); 


URI uri = uriComponents.expand("42", "21").encode().toUri(); 


请 注意 Uricomponents 是 不 可 变 对 象 。 因 此 expand() 4 encode() 操作 在 必要 的 时 候 会 返回 一 
个 新 的 实例 。 


你 也 可 以 使 用 一 个 URI 组 件 实例 对 象 来 实现 URI 的 填充 与 加 密 : 


UriComponents uriComponents = UriComponentsBuilder .newInstance() 
.scheme("http").host("example.com").path("/hotels/{hotel}/bookings/{booking}") 
.build() 
.expand( "42", "21") 
.encode(); 


在 Servlet 环 境 下 ， ServletUriComponentsBuilder 类 提供 了 一 个 静态 的 工厂 方法 ， 可 以 用 于 从 
Servlet 请 求 中 获取 URL 信 息 : 


HttpServletRequest request =... 





ServletUriComponentsBuilder ucb = ServletUriComponentsBuilder .fromRequest (request) 
.replaceQueryParam("accountId", "{id}").build() 
.expand("123") 
.encode(); 


或 者 ， 你 也 可 以 选择 只 复 用 请 求 中 一 部 分 的 信息 : 


// 重用 主机 名 、 端 口号 和 context path 
// 在 路 径 后 添加 "/accounts" 


ServletUriComponentsBuilder ucb = ServletUriComponentsBuilder.fromContextPath(requ 


est) 
.path("/accounts").build() 


或 者 ， 如 果 你 的 Dispatcherservlet 是 通过 名 字 (比如 ， /main/* ) 映射 请 求 的 ，you can 
also have the literal part of the servlet mapping included: 


// Re-use host, port, context path 
// Append the literal part of the servlet mapping to the path 
// Append "/accounts" to the path 


ServletUriComponentsBuilder ucb = ServletUriComponentsBuilder.fromServletMapping(r 


equest) 
.path("/accounts").build() 


21.7.1 为 控制 并 和 方法 指定 URI 


Spring MVC 也 提供 了 构造 指定 控制 器 方法 链接 的 机 制 。 以 下 面 代 码 为 例子 ， 假 设 我 们 有 这 样 


一 个 控制 器 : 


aa ¢ 


@Controller 
@RequestMapping("/hotels/{hotel}") 
public class BookingController { 


@RequestMapping("/bookings/{booking}") 
public String getBooking(@PathVariable Long booking) { 


Mb sant 


你 可 以 通过 引用 方法 名 字 的 办 法 来 准备 一 个 链接 : 


UriComponents uriComponents = MvcUriComponentsBuilder 
. FromMethodName(BookingController.class, "getBooking", 21).buildAndExpand(42); 


URI uri = uriComponents.encode().toUri(); 


在 上 面 的 例子 中 ， 我 们 为 方法 参数 准备 了 填充 值 : 一 个 long 型 的 变量 值 21， 以 用 于 填充 路 径 
变量 并 插入 到 URL 中 。 另 外 ， 我 们 还 提供 了 一 个 值 42， 以 用 于 填充 其 他 剩余 的 URI 变 量 ， 比 如 
从 类 层级 的 请 求 映 射 中 继承 来 的 hotel 变量 。 如 果 方 法 还 有 更 多 的 参数 ， 你 可 以 为 那些 不 需 
要 参与 URL 构 造 的 变量 赋予 null 值 。 一 般 而 言 ， 只 有 @pathvariable 和 @RequestParam 注解 的 
参数 才 与 URL 的 构造 相关 。 


还 有 其 他 使 用 MvcuricomponentsBuilder 的 方法 。 上 比如， 你 可 以 通过 类 似 mock 掉 测试 对 象 的 方 
法 ， 用 代理 来 避免 直接 通过 名 字 引 用 一 个 控制 器 方法 (以 下 方法 假 
设 MvcUricomponentsBuilder.on 方法 已 经 被 静态 导入 ) 


UriComponents uriComponents = MvcUriComponentsBuilder 
. FfromMethodCall(on(BookingController.class) .getBooking( 21) ).buildAndExpand( 42); 


URI uri = uriComponents.encode().toUri(); 
上 面 的 代码 例子 中 使 用 了 mMvcuricomponentsBuilder 类 的 静态 方法 。 内 部 实现 中 ， 它 依赖 


于 servleturicomponentsBuilder 来 从 当前 请 求 中 抽取 Schema、 主 机 名 、 端 口号 、context 路 径 
和 servlet 路 径 ， 并 准备 一 个 基本 URL。 大 多 数 情况 下 它 能 良好 工作 ， 但 有 时 还 不 行 。 比 如 ， 


在 准备 链接 时 ， 你 可 能 在 当前 请 求 的 上 下 文 (context) 之 外 《〈 比 如， 执行 一 个 准备 链接 links 
的 批 处 理 ) ， 或 你 可 能 需要 为 路 径 播 入 一 个 前 组 (比如 一 个 地 区 性 前 级， 它 从 请 求 中 被 移 
除 ， 然 后 又 重新 被 插入 到 链接 中 去 ) 。 


对 于 上 面 所 提 的 场景 ， 你 可 以 使 用 重 载 过 的 静态 方法 fromXxx ， 它 接收 一 

个 UriComponentsBuilder 参数 ， 然 后 从 中 获取 基本 URL 以 便 使 用 。 或 你 也 可 以 使 用 一 个 基本 
URL 创 建 一 个 mvcuricomponentsBuilder 对 象 ， 然 后 使 用 实例 对 象 的 fromxxx 方法 。 如 下 面 的 
示例 : 


UriComponentsBuilder base = ServletUriComponentsBuilder.fromCurrentContextPath().path( 
"fen" Ne 

MvcUriComponentsBuilder builder = MvcUriComponentsBuilder.relativeTo(base) ; 

builder .withMethodCall(on(BookingController.class).getBooking(21)).buildAndExpand(42); 


URI uri = uriComponents.encode().toUri(); 


在 视图 中 为 控制 医 和 方法 指定 URI 


21.8 地 区 信息 (Locales) 


Spring 的 架构 中 的 很 多 层面 都 提供 了 对 国际 化 的 支持 ， 同 样 支 持 Spring MVC 框 架 也 能 提 
供 。 DispatcherServlet 为 你 提供 了 自动 使 用 用 户 的 地 区 信息 来 解析 消息 的 能 力 。 而 这 ， 是 通 
过 LocaleResolver 对 象 来 完成 的 。 


一 个 请 求 进入 处 理 时 ” DispatcherServlet 会 查找 一 个 地 区 解析 器 。 如 果 找 到 ， 就 尝试 使 用 它 
来 设置 地 区 相关 的 信息 。 通 过 调用 RequestContext.getLocale() 都 能 取 到 地 区 解析 器 所 解析 到 
的 地 区 信息 。 


此 外 ， 如 果 你 需要 自动 解析 地 区 信息 ， 你 可 以 在 处 理 器 映射 前 加 一 个 拦截 器 〈 关 于 更 多 处 理 
器 映射 拦截 器 的 知识 ， 请 参见 21.4.1 使 用 Handlerlnterceptor 拦 堆 请 求 一 小 节 ) ， 并 用 它 来 根 
据 条 件 或 环境 不 同 ， 比如， 根据 请 求 中 茶 个 参数 值 ， 来 更 改 地 区 信息 。 


21.8.1 获取 时 区 信息 


除了 获取 客户 端的 地 区 信息 外 ， 有 时 他 们 所 在 的 时 区 信息 也 非常 有 
用 。 LocalecontextResolver 接口 为 LocaleResolver 提供 了 拓展 点 ? 允许 解析 器 
在 LocaleContext 中 提供 更 多 的 信 息 $ 这 里 面 就 可 以 包含 时 区 信 息 


如 果 用 户 的 时 区 信 息 能 被 解析 到 > 那么 你 总 可 以 通过 RequestContext.getTimeZone() 方法 获 
得 。 时 区 信息 会 自动 被 Spring conversionservice 下 注册 的 日 期 /时 间 转 换 器 converter 及 格式 
化 对 象 Formatter 所 使 用 。 


21.8.2 Accept 请 求 头 解析 器 
AcceptHeaderLocaleResolver 
AcceptHeaderLocaleResolver 解析 器 会 检查 客户 端 (比如 ， 浏 览 器 ， 等 ) 所 发 送 的 请 求 中 是 否 


览 
携带 accept-language 请 求 头 。 通 常 ， 该 请 求 头 字 段 中 包含 了 客户 端 操作 系统 的 地 区 信息 。 不 
过 请 注意 ， 该 解析 器 不 支持 时 区 信息 的 解析 。 


21.8.3 Cookie #77 4 CookieLocaleResolver 


CookieLocaleResolver 解析 会 检查 客户 端 是 否 有 cookie ， 里 面 可 能 存放 了 地 区 Locale 或 时 
区 Timezone 信息 。 如 果 检 查 到 相应 的 值 ， 解 析 器 就 使 用 它们 。 通 过 该 解析 器 的 属性 ， 你 可 以 
指定 cookie 的 名 称 和 其 最 大 的 存活 时 间 。 请 见 下 面 的 例子 ， 它 展示 了 如 何 定 义 一 


个 cookieLocaleResolver 


<bean id="localeResolver" class="org.springframework.web.servlet.ii8n.CookieLocaleReso 
lver"> 


<property name="cookieName" value="clientlanguage"/> 


<!-- 单位 为 秒 。 老 设置 为 -1， 则 cookie 和 不 会 被 持久 化 〈 客 己 端 关闭 浏览 颈 后 即 被 删除 = 


<property name="cookieMaxAge" value="100000"> 


</bean> 


表 21.4. CookieLocaleResolver 支 持 的 属性 


属性 默认 值 描 


让 


classname + 


LOCALE cookie 名 


cookieName 


cookie 被 保存 在 客户 端的 最 长 时 间 。 如 果 该 值 
cookieMaxAge Integer.MAX_INT 为 -1， 那 么 cookie 将 不 会 被 持久 化 ， 在 客户 端 浏 
览 器 关闭 之 后 就 失效 了 


限制 了 cookie 仅 对 站 点 下 的 某 些 特定 路 径 可 见 。 
cookiePath / 如 果 指 定 了 cookiePath， 那 么 cookie 将 仅 对 该 路 
径 及 其 子路 径 下 的 所 有 站 点 可 见 


21.8.4 Session ff» & 
SessionLocaleResolver 


SessionLocaleResolver 允许 你 从 session 中 取得 可 能 与 用 户 请 求 相 关联 的 地 区 Locale 和 时 
区 Timezone 信息 。 与 cookieLocaleResolver 不 同 ， 这 种 存 取 策 略 仅 将 Servlet 容 器 

的 Httpsession 中 相关 的 地 区 信息 存 取 到 本 地 。 因 此 ， 这 些 设置 仅 会 为 该 会 话 (session) 临 
时 保存 ，session 结 束 后 ， 这 些 设置 就 会 失效 。 


不 过 请 注意 ， 该 解析 器 与 其 他 外 部 Session 管理 机 制 ， 比 如 Spring 的 Session 项 目 等 ， 并 没有 直 
接 联系 。 该 SessionLocaleResolver 仅 会 简 单 地 从 与 当 前 请 求 HttpServletRequest 相关 
的 HttpSession 对 象 中 ， 取 出 对 应 的 属性 ， 并 修改 其 值 ， 仅 此 而 已 。 


21.8.5 地 区 更 改 拦 规 器 
LocaleChangelnterceptor 


You can enable changing of locales by adding the LocalechangeInterceptor to one of the 
handler mappings (see [Section 21.4, "Handler mappings"](mvc.html 


mvc-handlermapping "21.4 Handler 
mappings" )). It will detect a parameter in 


the request and change the locale. It calls setLocale() onthe LocaleResolver that also 
exists in the context. The following example shows that calls to all *.view resources 
containing a parameter named siteLanguage will now change the locale. So, for example, a 
request for the following URL, <http://ww.sf.net/home.view?siteLanguage=nl> will change 
the site language to Dutch. 


你 可 以 在 处 理 器 映射 ( 详 见 21.4 处 理 器 映射 (Handler mappings) 小 节 ) 前 添加 一 

个 LocaleChangeInterceptor 拦截 器 来 更 改 地 区 信息 。 它 能 检测 请 求 中 的 参数 ， 并 根据 其 值 相 
应 地 更 新 地 区 信息 。 它 通过 调用 LocaleResolver 的 SetLocale() 方法 来 更 改 地 区 。 下 面 的 代 
码 配 置 展 示 了 如 何 为 所 有 请 求 *.view 路 径 并 且 携 带 了 siteLanguage 参数 的 资源 请 求 更 改 地 
区 。 举 个 例子 ， 一 个 URL 为 <http://www.sf.net/home.view?siteLanguage=nl> 的 请 求 将 会 将 站 
点 语言 更 改 为 荷兰 语 。 


地 区 更 改 拦截 器 LocaleChangelnterceptor 


<bean id="localeChangeInterceptor" class="org.springframework.web.servlet.i18n.Localec 
hangeInterceptor"> 

<property name="paramName" value="siteLanguage"/> 
</bean> 


<bean id="localeResolver" class="org.springframework.web.servlet.i18n.CookieLocaleReso 
Ver 全 


<bean id="urlMapping" class="org.springframework.web.servlet.handler.SimpleUrlHandlerm 


apping"> 
<property name="interceptors"> 
<list> 
<ref bean="localeChangeInterceptor"/> 
</list> 
</property> 


<property name="mappings"> 
<value>/**/* ,view=someController</value> 
</property> 
</bean> 
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21.9 + themes 


©2191 关于 主题 : 概览 
© 21.9.2 定义 主题 
。 21.9.3 主题 解析 器 


21.9.1 关于 主题 : 概览 


You can apply Spring Web MVC framework themes to set the overall look-and-feel of your 
application, thereby enhancing user experience. A theme is a collection of static resources, 
typically style sheets and images, that affect the visual style of the application. 


你 可 以 使 用 Spring Web MVC 框 架 提 供 的 主题 来 为 整 站 的 应 用 设置 皮肤 /主题 (look-and- 
feel) ， 这 可 以 提高 用 户 体验 。 主 题 是 指 一 系列 静态 资源 的 集合 ， 并 且 主 要 是 样式 表 和 图 片 ， 
它们 决定 了 你 的 应 用 的 视觉 风格 。 


21.9.2 定义 主题 


要 在 你 的 应 用 中 使 用 主题 ， 你 必须 实现 一 个 org.springframework.ui.context.ThemeSource 接 
口 。 WebApplicationContext 接口 继承 了 Themesource 接口 ， 但 主要 的 工作 它 还 是 委托 给 接口 
具体 的 实现 来 完成 。 默 认 的 实现 

是 org.springframework.ui.context.support.ResourceBundleThemeSource ? € & classpath 49 4k 

路 径 下 去 加 载 配置 文件 。 如 果 需 要 定制 ThemeSource 的 实现 ， 或 要 配 

置 ResourceBundleThemeSource 的 基本 前 级 名 (base name prefix) ， 你 可 以 在 应 用 上 下 文 
(application context) 下 注册 一 个 名 字 为 保留 名 themesource 的 bean，web 应 用 的 上 下 文 会 
自动 检测 名 字 为 themesource 的 bean 并 使 用 它 。 


使 用 的 是 ResourceBundleThemeSource 时 ， 一 个 主题 可 以 定义 在 一 个 简单 的 配置 文件 中 。 该 配 
置 文件 会 列 出 所 有 组 成 了 该 主题 的 资源 。 下 面 是 个 例子 : 


styleSheet=/themes/cool/style.css 
background=/themes/cool/img/coolBg. jpg 


属性 的 键 (key) 是 主题 元 素 在 视图 代码 中 被 引用 的 名 字 。 对 于 JSP 视 图 来 说 ， 一 般 通 
过 spring:theme 这 个 定制 化 的 标签 (tag) 来 做 ， 它 与 spring:message 标签 很 相似 。 以 下 的 
JSP 代 码 即 使 用 了 上 上 段 代 码 片段 中 定义 的 主题 ， 用 以 定制 整体 的 皮肤 : 


<%@ taglib prefix="spring" uri="http://www.springframework.org/tags"%> 
<html> 
<head> 
<link rel="stylesheet" href="<spring: theme code=''styleSheet''/>" type="text/c 
SH /> 
</head> 


<body style="background=<spring: theme code=''background''/>"> 
</body> 
</html> 


默认 情况 下 ResourceBundlethemeSource 使 用 的 基本 名 前 缓 (base name prefix) 是 空 值 。 也 即 
是 说 ， 配 置 文件 是 从 根 classpath 路 径 下 加 载 的 。 因 此 ， 你 需要 把 主题 的 定义 文 

件 cool.properties 放 在 classpath 的 根 路 径 目录 下 ， 比 如 ， /WEB- 

INF/classes ° ResourceBundleThemeSource 采用 了 Java 的 标准 资源 bundle 加 载 机 制 ， 完 全 支持 
国际 化 主题 。 上 比如， 你 可 以 创建 一 个 /WEB-INF/classes/cool_nl.properties 配置 文件 ， 并 在 其 
中 引用 一 副 有 和 荷兰 文 的 背景 图 片 。 


定义 主题 
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21.9.3 主题 解析 器 


上 一 小 节 ， 我 们 讲 了 如 何 定 义 主 题 ， 定 义 之 后 ， 你 要 决定 使 用 哪个 主 

题 。 DispatcherServlet 会 查找 一 个 名 称 为 themeresolver 的 bean 以 确定 使 用 哪 

个 ThemeResolver 的 实现 。 主 题解 析 器 的 工作 原理 与 地 区 解析 器 LocaleResolver 的 工作 原理 大 
同 小 异 。 它 会 检测 ， 对 于 一 个 请 求 来 说 ， 应 该 使 用 哪个 主题 ， 同 时 它 也 可 以 修改 一 个 请 求 所 
应 应 用 的 主题 。Spring 提 供 了 下 列 的 这 些 主题 解析 器 : 


表 21.5. ThemeResolver 接 口 的 实现 


类 名 描述 
选择 一 个 固 定 的 主题 ， 这 是 通过 设置 defaultThemeName 这 个 属 

FixedThemeResolver £ 
性 值 实现 的 
请 求 相 关 的 主题 保存 在 用 户 的 HTTP 会 话 (session) 中 。 对 于 

SessionThemeResolver 每 个 会 话 来 说 ， 它 只 需要 被 设置 一 次 ， 但 它 不 能 在 会 话 之 间 保 
存 

CookieThemeResolver 选中 的 主题 被 保存 在 客户 端的 cookie 中 


Spring 也 提供 了 一 个 主题 更 改 拦截 器 ThemeChangeInterceptor ? 以 支持 主题 的 更 换 。 这 很 容 多 
做 到 ， 只 需要 在 请 求 中 携带 一 个 简单 的 请 求 参 数 即 可 。 


21.10 Spring J multipart (文件 上 传 ) 支持 


o 概述 

使 用 MultipartResolver 与 Commons FileUpload 传 输 文件 
Servlet 3.0 下 的 MultipartResolver 

处 理 表单 中 的 文件 上 传 

处 理 客户 端 发 起 的 文件 上 传 请 求 


21.10.14 概述 


Spring 内 置 对 多 路 上 传 的 支持 ， 专 门 用 于 处 理 Web 应 用 中 的 文件 上 传 。 你 可 以 通过 注册 一 个 可 
插 拔 的 MultipartResolver 对 象 来 启用 对 文件 多 路 上 传 的 支持 。 该 接口 在 定义 

ig org.springframework.web.multipart 包 下 。 Spring 为 一 般 的 文件 上 传 提 供 

了 MultipartResolver 接口 的 一 个 实现 ， 为 Servlet 3.0 多 路 请 求 的 转换 提供 了 另 一 个 实现 。 


默认 情况 下 ，Spring 的 多 路 上 传 支持 是 不 开启 的 ， 因 为 有 些 开发 者 希望 由 自己 来 处 理 多 路 请 
求 。 如 果 想 启用 Spring 的 多 路 上 传 支持 ， 你 需要 在 web 应 用 的 上 下 文中 添加 一 个 多 路 传输 解析 
器 。 每 个 进来 的 请 求 ， 解 析 器 都 会 检查 是 不 是 一 个 多 部 分 请 求 。 若 发 现 请 求 是 完整 的 ， 则 请 
求 按 正 常 流程 被 处 理 ; 如 果 发 现 请 求 是 一 个 多 路 请 求 ， 则 你 在 上 下 文中 注册 

的 MultipartResolver 解析 器 会 被 用 来 处 理 该 请 求 。 之 后 ， 请 求 中 的 多 路 上 传 属性 就 与 其 他 属 
性 一 样 被 正常 对 待 了 。 【最 后 一 句 翻 的 不 好 ，multipart 翻 译 成 多 路 还 是 多 部 分 还 在 贡 酌 中 。 望 
阅读 者 注意 此 处 。】 


21.10.2 4% 4] MultipartResolver5 Commons 
FileUpload 传 输 文件 


下 面 的 代码 展示 了 如 何 使 用 一 个 通用 的 多 路 上 传 解析 器 commonsMultipartResolver 


<bean id="multipartResolver" class="org.springframework.web.multipart.commons.CommonsM 
ultipartResolver"> 


<property name="maxUploadSize" value="100000"/> 


</bean> 


当然 ， 要 让 多 路 解析 器 正常 工作 ， 你 需要 在 classpath 路 径 下 准备 必须 的 jar 包 。 如 果 使 用 的 是 
通用 的 多 路 上 传 解析 器 CommonsMultipartResolver ” 你 所 需要 的 jar 包 是 commons- 


fileupload.jar ° 


当 Spring 的 Dispatcherservlet 检测 到 一 个 多 部 分 请 求 时 ， 它 会 激活 你 在 上 下 文中 声明 的 多 路 
解析 器 并 把 请 求 交 给 它 。 解 析 器 会 把 当前 HttpServletRequest 请 青 求 对 象 包装 成 一 个 支持 多 

路 文件 上 传 的 请 求 对 象 nee SASS eS S WAL. gp 对 

象 ， 你 不 仅 可 以 获取 该 多 路 请 求 中 的 信息 ， 还 可 以 在 你 的 控制 器 中 获得 该 多 路 请 求 的 内 容 本 
身 。 


21.10.3 Servlet 3.0 T 49 MultipartResolver 


要 使 用 基于 Servlet 3.0 的 多 路 传输 转换 功能 ， 你 必须 在 web.xml 中 为 DispatcherServlet 添加 
一 个 multipart-config 元 素 ， 或 者 通过 Servlet 编 程 的 方法 使 

用 javax.servlet.MultipartConfigElement 进行 注册 ， 或 你 自己 定制 了 自己 的 Servlet 类 ， 那 你 
必须 使 用 javax.servlet.annotation. ESE 对 其 L att 47 1 AR o 其 他 诸如 最 大 文件 大 小 或 
存储 位 置 等 配置 选项 都 必须 在 这 个 Servlet 级 别 进 行 注册 ， 因 为 Servlet 3.0 不 允许 在 解析 器 
MultipartResolver 的 层级 配置 这 些 信 息 。 


当 你 通过 以 上 任 一 种 方式 启用 了 Servlet 3.0 多 路 传输 转换 功能 ， 你 就 可 以 把 一 
个 StandardServletMultipartResolver 解析 器 添加 到 你 的 Spring 配置 中 去 了 : 


<bean id="multipartResolver" class="org.springframework.web.multipart.support.Standard 
ServletMultipartResolver"> 
</bean> 


21.10.4 处 理 表 单 中 的 文件 上 传 


当 解 析 器 MultipartResolver 完成 处 理 时 ， 请 求 便 会 像 其 他 请 求 一 样 被 正常 流程 处 理 。 首 先 ， 
创建 一 个 接受 文件 上 传 的 表单 将 允许 用 于 直接 上 传 整 个 表单 。 编 码 属性 
( enctype="multipart/form-data" ) 能 让 浏览 器 知道 如 何 对 多 路 上 传 请 求 的 表单 进行 
(encode) 。 


<html> 
<head> 
<title>Upload a file please</title> 
</head> 
<body> 
<hi>Please upload a file</h1i> 
<form method="post" action="/form" enctype="multipart/form-data"> 
<input type="text" name="name"/> 
<input type="file" name="file"/> 
<input type="Submit"/> 
</form> 
</body> 
</html> 
下 一 步 是 创建 一 个 能 处 理 文件 上 传 的 控制 器 。 这 里 需要 的 控制 器 与 一 般 注 解 了 controller 的 
控制 器 基本 一 样 ， 除 了 它 接受 的 方法 参数 类 型 是 multipartuttpServletRequest ， 


或 MultipartFile 。 


@Controller 
public class FileUploadController { 


@RequestMapping(path = "/form", method = RequestMethod.POST) 
public String handleFormUpload(@RequestParam("name") String name, @RequestParam("f 
ile) MULeiparteale hale) 


if (!file.isEmpty()) { 
byte[] bytes = file.getBytes(); 
// store the bytes somewhere 
return "redirect: uploadSuccess"; 


return "redirect: uploadFailure"; 


请 留意 @RequestParam 注解 是 如 何 将 方法 参数 对 应 到 表单 中 的 定义 的 输入 字段 的 。 在 上 面 的 例 
子 中 ， 我 们 拿 到 了 byte[] 文件 数据 ， 只 是 没 对 它 做 任何 事 。 在 实际 应 用 中 ， 你 可 能 会 将 它 保 
存 到 数据 库 、 存 储 在 文件 系统 上 ， 或 做 其 他 的 处 理 。 


当 使 用 Servlet 3.0 的 多 路 传输 转换 时 ， 你 也 可 以 使 用 javax.servlet.http.part 作为 方法 参 
数 : 


@Controller 
public class FileUploadController { 


@RequestMapping(path = "/form", method = RequestMethod.POST) 
public String handleFormUpload(@RequestParam("name") String name, @RequestParam("f 


lie) Rare halle) et 


InputStream inputStream = file.getInputStream(); 
// store bytes from uploaded file somewhere 


return "redirect:uploadSuccess"; 


As 


21.10.5 处 理 客户 端 发 起 的 文件 上 传 请 求 


在 使 用 了 RESTful 服 务 的 场景 下 ， 非 浏览 器 的 客户 端 也 可 以 直接 提交 多 路 文件 请 求 。 上 一 节 讲 
述 的 所 有 例子 与 配置 在 这 里 也 都 同样 适用 。 但 与 浏览 器 不 同 的 是 ， 提 交 的 文件 和 简单 的 表单 
字段 ， 客 户 端 发 送 的 数据 可 以 更 加 复杂 ， 数 据 可 以 指定 为 某 种 特定 的 内 容 类 型 (content 
type) 一 一 比如 ， 一 个 多 路 上 传 请 求 可 能 第 一 部 分 是 个 文件 ， 而 第 二 部 分 是 个 JSON 格 式 的 数 
据 : 


POST /someUrl 
Content-Type: multipart/mixed 


--edt7Tfrdusa7r31NQc79vXuhIIMlatb7PQg7Vp 
Content-Disposition: form-data; name="meta-data" 
Content-Type: application/json; charset=UTF-8 
Content-Transfer-Encoding: 8bit 


"name": "value" 


} 
--edt7Tfrdusa7r31NQc79vXuhIIMlatb7PQg7Vp 


Content-Disposition: form-data; name="file-data"; filename="file.properties" 
Content-Type: text/xml 
Content-Transfer-Encoding: 8bit 

. File Data ... 


对 于 名 称 为 meta-data 的 部 分 ， 你 可 以 通过 控制 器 方法 上 的 @RequestParam("meta-data") 
String metadata 参数 来 获得 。 但 对 于 那 部 分 请 求 体 中 为 JSON 格 式 数据 的 请 求 ， 你 可 能 更 想 通 
过 接受 一 个 对 应 的 强 类 型 对 象 ， 就 像 @RequestBody 通过 HttpMessageConverter 将 一 般 请 求 的 
请 求 体 转换 成 一 个 对 象 一 样 。 


这 是 可 能 的 ， 你 可 以 使 用 @RequestPart 注解 来 实现 ， 而 非 @RequestParam ° 该 注解 将 使 得 特 
定 多 路 请 青 求 的 请 求 体 被 传 给 HttpMessageConverter ， 并 且 在 转换 时 考虑 多 多 路 请 求 中 不 同 的 内 容 
米 

R 


EG 参数 ‘content - -Type' 


= 


@RequestMapping(path = "/someUr1", method = RequestMethod. POST) 
public String onSubmit(@RequestPart("meta-data") MetaData metadata, @RequestPart("file 
-data") MultipartFile file) { 


IS aa 


请 注意 MultipartFile 方法 参数 是 如 何 能 够 在 @RequestParam 或 @RequestPart 注解 下 互 用 的 ? 
两 种 方法 都 能 拿 到 数据 。 但 ， 这 里 的 方法 参数 @RequestPart("meta-data") MetaData 则 会 因为 
请 求 中 的 内 容 类 型 请 求 头 "Content-Type' 被 读 入 成 为 JSON 数 据 ， 然 后 再 通 

过 MappingJackson2HttpMessageConverter 被 转换 成 特定 的 对 象 2 


异常 处 理 


21.11 FRR 


处 理 器 异常 解析 器 HandlerExceptionHandler 
e @ExceptionHandler 注 解 

处 理 一 般 的 Spring MVC 异 常 

e 4% M @ResponseStatus iz ff 1k FH % 
Servlet 默 认 容 器 错误 页 面 的 定制 化 
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21.11.1 LEB HH MITA 
HandlerExceptionHandler 


Spring 的 处 理 器 异常 解析 器 HandlerExceptionResolver 接口 的 实现 负责 处 理 各 类 控制 器 执行 过 
程 中 出 现 的 异常 Q 某 种 程度 上 讲 ， HandlerExceptionResolver 与 你 在 web 应 用 描述 

符 web.xml 文件 中 能 定义 的 异常 映射 (exception mapping) 很 相像 ， 不 过 它 比 后 者 提供 了 更 
灵活 的 方式 。 比 如 它 能 提供 异常 被 抛 出 时 正在 执行 的 是 哪个 处 理 器 这 样 的 信息 。 并 且 ， 一 个 

更 灵活 (programmatic) 的 异常 处 理 方式 可 以 为 你 提供 更 多 选择 ， 使 你 在 请 求 被 直接 转向 到 

另 一 个 URL 之 前 〈 与 你 使 用 Servlet 规 范 的 异常 映射 是 一 样 的 ) 有 更 多 的 方式 来 处 理 异 常 


实现 HandlerExceptionResolver 接口 并 非 实 现 异 常 处 理 的 唯一 方式 ， 它 只 是 提供 

了 resolveException(Exception, Hanlder) 方法 的 一 个 实现 而 已 ， 方 法 会 返回 一 

个 ModelAndview 。 除 此 之 外 ， 你 还 可 以 框架 提供 的 SimpleMappingExceptionResolver 或 在 异常 
处 理 方法 上 注解 @ExceptionHandler ° SimpleMappingExceptionResolver 允许 你 获取 可 能 抛 出 的 
异常 类 的 名 字 ， 并 把 它 映射 到 一 个 视图 名 上 去 。 这 与 Servlet API 提 供 的 异常 映射 特性 是 功能 
等 价 的 ， 但 你 也 可 以 基于 此 实现 粒度 更 精细 的 异常 映射 。 而 @ExceptionHandler 注解 的 方法 则 
会 在 异常 抛 出 时 被 调用 以 处 理 该 异常 。 这 样 的 方法 可 以 定义 在 @controller 注解 的 控制 器 类 
里 ， 也 可 以 定义 在 @controllerAdvice 类 中 ， 后 者 可 以 使 该 异常 处 理 方法 被 应 用 到 更 多 

的 @controller 控制 器 中 。 下 一 小 节 将 提供 更 为 详细 的 信息 


21.11.2 @ExceptionHandler ‘=z F 


HandlerExceptionResolver 接口 以 及 SimpleMappingExceptionResolver 解析 器 类 的 实现 使 得 你 
能 声明 式 地 将 异常 映射 到 特定 的 视图 上 ， 还 可 以 在 异常 被 转发 〈forward) 到 对 应 的 视图 前 使 
用 Java 代 码 做 些 判断 和 逮 辑 。 不 过 在 一 些 场景 ， 特 别 是 依靠 @ResponseBody 返回 响应 而 非 依 赖 
视图 解析 机 制 的 场景 下 ， 直 接 设 置 响 应 的 状态 码 并 将 客户 端 需要 的 错误 信息 直接 写 回 响应 体 
中 ， 可 能 是 更 方便 的 方法 。 


你 也 可 以 使 用 @ExceptionHandler 方法 来 做 到 这 点 。 如 果 @ExceptionHandler 方法 是 在 控制 器 
内 部 定义 的 ， 那 么 它 会 接收 并 处 理由 控制 器 〈 或 其 任何 子 类 ) 中 的 @RequestMapping 方法 抛 出 
的 异常 。 如 果 你 将 @ExceptionHandler 方法 定义 在 @controllerAdvice 类 中 ， 那 么 它 会 处 理 相 
关 控 制 器 中 抛 出 的 异常 oF ma 代码 就 展示 了 一 个 定义 在 控制 器 内 部 的 @ExceptionHandler 方 
法 : 


@Controller 
public class SimpleController { 


// @RequestMapping methods omitted .. 


@ExceptionHandler (IOException.class) 
public ResponseEntity<String> handleIOException(IOException ex) { 
// prepare responseEntity 


return responseEntity; 


此 外 ， @ExceptionHandler 注解 还 可 以 接受 一 个 异常 类 型 的 数组 作为 参数 值 。 若 抛 出 了 已 在 列 
表 中 声明 的 异常 ， 那 么 相应 的 @ExceptionHandler 方法 将 会 被 调用 。 如 果 没 有 给 注解 任何 参数 
值 ， 那 么 默认 处 理 的 异常 类 型 将 是 方法 参数 所 声明 的 那些 异常 。 


与 标准 的 控制 器 @RequestMapping 注解 处 理 方法 一 样 ， @ExceptionHandler 方法 的 方法 参数 和 
返回 值 也 可 以 很 灵活 。 比 如 ， 在 Servlet 环 境 下 方法 可 以 接收 HttpservletRequest #2? mn 
Portlet 环 境 下 方法 可 以 接收 portletRequest 参数 。 返 回 值 可 以 是 string 类 型 这 种 情况 下 
会 被 解析 为 视图 名 一 一 可 以 是 ModelAndview 类 型 的 对 象 ， 也 可 以 是 ResponseEntity ° 或 者 你 
还 可 以 在 方法 上 添加 @ResponseBody 注解 以 使 用 消息 转换 器 会 转换 信息 为 特定 类 型 的 数据 ， 然 
后 把 它们 写 回 到 响应 流 中 。 





21.11.3 处 理 一 般 的 Spring MVC 异 常 


处 理 请 求 的 过 程 中 ，Spring MVC 可 能 会 抛 出 一 些 的 异常 


° SimpleMappingExceptionResolver 可 


以 根据 需要 很 方便 地 将 任何 异常 映射 到 。 但 ， 如 果 客 户 端 是 通过 自动 检 


测 响 应 的 方式 来 分 发 处 理 异常 的 ， 那 么 


a 


(5xx) ° 


默认 处 理 器 异常 解析 器 


DefaultHandlerExceptionResolver 


对 应 的 错误 状态 码 。 该 解析 器 在 MVC 命 名 空间 配置 


端 就 需要 为 响应 设置 对 应 的 状态 码 。 R 


FUR (4xx) 还 是 服务 器 端 错 


会 将 Spring MVC 抛 出 的 异常 转换 成 
或 MVC Java 配 置 的 方式 下 默认 已 经 被 注册 


了 ， 另 外 ， 通 过 Dispatcherservlet 注册 也 是 可 行 的 ran MVC 命 名 空间 或 Java 编 程 方式 


进行 配置 的 时 候 ) 。 下 表 列 出 了 该 解析 器 能 处 


异常 
BindException 
ConversionNotSupportedException 
HttpMediaTypeNotAcceptableException 
HttpMediaTypeNotSupportedException 
HttpMessageNotReadableException 
HttpMessageNotWritableException 
HttpRequestMethodNotSupportedException 
MethodArgumentNotValidException 
MissingServletRequestParameterException 
MissingServletRequestPartException 
NoHandlerFoundException 
NoSuchRequestHandlingMethodException 
TypeMismatchException 
MissingPathVariableException 


NoHandlerFoundException 


， 及 他 们 对 应 的 状态 码 。 


HTTP 状 态 码 
400 (无 效 请 求 ) 
500 (服务 器 内 部 错误 ) 
406 (不 


4 


( 

( 

(不 接受 ) 
415 (不 支持 的 媒体 类 型 ) 
400 (无 效 请 求 ) 
500 (服务 器 内 部 错误 ) 
405 (不 支持 的 方法 ) 
400 (无 效 请 求 ) 
400 (无 效 请 求 ) 
400 (无 效 请 求 ) 
404 (请 求 未 找到 ) 
404 (请 求 未 找到 ) 
400 (无 效 请 求 ) 
500 (服务 器 内 部 错误 ) 
404 (请 求 未 找到 ) 


以 下 待 翻译 。 


The pefaultHandlerExceptionResolver works transparently by setting the status of the 
response. However, it stops short of writing any error content to the body of the response 
while your application may need to add developer- friendly content to every error response 


for example when providing a REST API. You can prepare a ModelAndview and render error 
content through view resolution -- i.e. by configuring a contentNegotiatingViewResolver , 

MappingJackson2JsonView , and so on. However, you may prefer to use @ExceptionHandler 
methods instead. 


If you prefer to write error content via @ExceptionHandler methods you can extend 

ResponseEntityExceptionHandler instead. This is a convenient base for @controllerAdvice 
classes providing an @ExceptionHandler method to handle standard Spring MVC exceptions 
and return ResponseEntity . That allows you to customize the response and write error 
content with message converters. See the ResponseEntityExceptionHandler javadocs for 
more details. 


21.11.4 使 用 @ResponseStatus 注 解 业务 弄 常 


业务 异常 可 以 使 用 @Responsestatus 来 注解 。 当 异常 被 抛 出 
时 ， ResponseStatusExceptionResolver 会 设置 相应 的 响应 状态 码 。 DispatcherServlet 会 默认 
注册 一 个 ResponseStatusExceptionResolver 以 供 使 用 。 


21.11.5 Servlet 默 认 容 器 错误 页 面 的 定制 化 


当 响 应 的 状态 码 被 设置 为 错误 状态 码 ， 并 且 响 应 体 中 没有 内 容 时 ，Servlet 容 器 通常 会 泻 染 一 
个 HTML 错 误 页 。 若 需要 定制 容器 默认 提供 的 错误 页 ， 你 可 以 在 web.xml 中 定义 一 个 错误 页 
面 <error-page> 元 素 。 在 Servlet 3 规范 出 来 之 前 ， 该 错误 页 元 素 必 须 被 显 式 指 定 映 射 到 一 
具体 的 错误 码 或 一 个 异常 类 型 。 从 Servlet 3 开始 ， 错 误 页 不 再 需要 映射 到 其 他 信息 了 ， ~*~ 
味 着 ， 你 指定 的 位 置 就 是 对 Servlet 容 器 默认 错误 页 的 自 定 制 了 。 


<error-page> 
<location>/error</location> 
</error -page> 


这 里 错误 页 的 位 置 所 在 可 以 是 一 个 JSP 页 面 ， 或 者 其 他 的 一 些 URL， 只 要 它 指定 容器 里 任意 一 
个 @controller 控制 器 下 的 处 理 器 方法 : 


写 回 HttpServletResponse 的 错误 信 ， 息 和 错 误 状 态 码 可 以 在 控盘 | 器 中 中 通过 请 求 属性 来 获取 : 


@Controller 
public class ErrorController { 


@RequestMapping(path = "/error", produces = MediaType.APPLICATION_JSON_UTF8_VALUE) 
@ResponseBody 
public Map<String, Object> handle(HttpServletRequest request) { 


Map<String, Object> map = new HashMap<String, Object>(); 
map.put("status", request.getAttribute("javax.servlet.error.status_code")); 
map.put("reason", request.getAttribute("javax.servlet.error.message")); 


return map; 


或 者 在 JSP 中 这 么 使 用 : 


<%@ page contentType="application/json" pageEncoding="UTF-8"%> 

{ 
status :<%=request.getAttribute("javax.servlet.error.status_code") %>, 
reason: <%=request.getAttribute("javax.servlet.error.message") %> 


Servlet 默 认 容 器 错误 页 面 的 定制 化 
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21.12 Webx# 


Spring Security 项 目 为 保护 web 应 用 免 受 恶意 攻击 提供 了 一 些 特 性 。 你 可 以 去 看 看 参考 文档 的 
这 几 小 节 : "CSRF 保 护 "、" 安 全 响应 头 "以 及 "Spring MVC 集 成 "。 不 过 并 非 应 用 的 所 有 特性 都 
需要 引入 Spring Security。 比 如 ， 需 要 CSRF 保 护 的 话 ， 你 仅 需 要 简单 地 在 配置 中 添加 一 个 过 
滤器 csrfFilter 和 处 理 器 csrfRequestDataValueProcessor 。 你 可 以 参考 Spring MVC 
Showcase 一 节 ， 观 看 一 个 完整 的 展示 。 


另 一 个 选择 是 使 用 其 他 专注 于 Web 安 全 的 框架 。HDIV 就 是 这 样 的 一 个 框架 ， 并 且 它 能 与 
Spring MVC 良 好 集成 。 


21.13 "约定 优 于 配置 "的 支持 


对 于 许多 项 目 来 说 ， 不 打破 已 有 的 约定 ， 对 于 配置 等 有 可 预测 的 默认 值 是 非常 适合 的 。 现 

E > Spring MVC 对 约定 优 于 配置 这 个 实践 已 经 有 了 显 式 的 支持 。 这 意味 着 什么 呢 ? 意味 着 
如 果 你 为 项 目 选择 了 一 组 命名 上 的 约定 /规范 ， 你 将 能 减少 KE 的 配置 项 ， 比 如 一 些 必要 的 处 
理 器 映射 、 视 图 解析 器 、 ModelAndview 实例 的 配置 等 。 这 能 帮 你 快速 地 建立 起 项 目 原型 ， 此 
外 在 某 种 程度 上 (通常 是 好 的 方面 ) 维护 了 整个 代码 库 的 一 致 性 should you choose to move 
forward with it into production. 


具体 来 说 ， 支 持 “ 约 定 优 于 配置 ”涉及 到 MVC 的 三 个 核心 方面 : 模型 、 视 图 ， 和 控制 器 。 


21.13.1 H E XZ -A IE R kA} 
ControllerClassNameHandlerMapping 


ControllerClassNameHandlerMapping 类 是 HandlerMapping HoA” Catei 
来 解析 请 求 URL 及 处 理 该 请 求 的 @controller 控制 器 实例 之 间 的 映射 关系 。 


请 看 下 面 一 个 简单 的 控制 器 实现 。 请 注意 留意 该 类 的 名 称 : 


public class **ViewShoppingCartController** implements Controller { 


public ModelAndView handleRequest(HttpServletRequest request, HttpServletResponse 
response) { 


// 这 个 例子 中 方法 的 具体 实现 并 不 重要 ， 故 忽略 


对 应 的 Spring Web MVC 配 置 文件 如 下 所 示 : 


<bean class="org.springframework.web.servlet.mvc.support.ControllerClassNameHandlerMap 
ping"/> 


<bean id="**viewShoppingCart**" class="x.y.z.ViewShoppingCartController"> 


<l-- 注入 需要 的 依赖 25 


</bean> 


SS 会 查找 当 前 应 用 上 下 文 中 注册 的 所 有 处 理 pa ( 也 即 控制 
器 ) bean， 并 去 除 类 名 的 controller 后 级 作为 决定 处 理 器 映射 的 依据 。 因 此 ， 类 
名 ViewShoppingCartController 会 被 映射 到 匹配 /viewshoppingcart* 8974 RURLE 2 


让 我 们 多 看 几 个 例子 ， 这 样 你 对 于 核心 的 思想 会 马上 熟悉 起 来 (注意 URL 中 路 径 是 全 小 写 ， 
而 Controller 控制 器 类 名 符合 驼峰 命 名 法 ) 


e WelcomeController 将 映射 到 /welcome* 请 求 URL 

© Homecontroller 将 映射 到 /home* 请 求 URL 

e IndexController 将 映射 到 /index* 请 求 URL 

e RegisterController 将 映射 到 /register* 请 求 URL 


对 于 MultiActioncontroller 处 理 器 类 ， 映 射 规则 要 稍微 复杂 一 些 。 请 看 下 面 的 代码 ， 假 设 这 
里 的 控制 器 都 是 MultiActioncontroller 的 实现 : 


© AdminController 将 映射 到 /admin/* 请 求 URL 
e catalogcontroller 将 映射 到 /catalog/* 请 求 URL 


只 要 所 有 控制 器 Controller 实现 都 遵循 xxxController 这 样 的 命名 PLIL > AB 
么 ControllerClassNameHandlerMapping 能 把 你 从 定义 维护 一 个 KKK 
SimpleUr lLHandlerMapping 映射 表 的 重复 工作 中 拯救 出 来 。 


ControllerClassNameHandlerMapping 类 继承 自 AbstractHandlerMapping 基 类 。 因 此 ， 你 可 以 视 
它 与 其 他 HandlerMapping 实现 一 样 ， 定 义 你 所 需要 的 拦截 器 HandlerInterceptor 实例 及 其 他 
所 有 东西 。 


21.13.2 7% 4%! ModelMap(ModelAndView) 


ModelMap 类 其 实 就 是 一 个 豪华 版 的 Map ， 它 使 得 你 为 视图 展示 需要 所 添加 的 对 象 都 遵循 一 
个 显而易见 的 约 定 被 命名 2 请 看 下 面 这 个 Controller 实现 ， 并 请 注意 ， 添 加 
到 ModelAndview 中 去 的 对 象 都 没有 显 式 地 指定 键 名 2 


public class DisplayShoppingCartController implements Controller { 


public ModelAndView handleRequest(HttpServletRequest request, HttpServletResponse 
response) { 


List cartItems = // 拿 到 一 个 CartItem 对 象 的 列表 





User user = // 
ModelAndView mav = new ModelAndView("displayShoppingCart"); <-- 逻辑 视图 名 


mav.addObject(cartItems); <-- 啊 哈 ， 直 接 添 加 的 对 象 ， 没 有 指定 名 称 
mav.addObject(user); <-- 啊 哈 再 来 一 次 


return mav; 


ModelAndview 内 部 使 用 了 一 个 ModelMap 类 ， 它 是 Map 的 一 个 实现 ， 会 自动 为 添加 进来 的 对 
象 生 成 一 个 键 名 。 为 添加 对 象 生 成 名 称 的 策略 是 ， 若 添加 对 象 是 一 个 纯 Java bean (a scalar 
Object) ， 比 如 user ， 那 么 使 用 对 象 类 的 短 类 名 (short class name) 来 作为 该 对 象 的 名 称 。 
下 面 是 一 些 例子 ， 展 示 了 为 添加 到 ModelMap 实例 中 的 纯 Java 对 象 所 生成 的 名 称 : 


e 添加 一 个 x.y.User 实例 ， 为 其 生成 的 名 称 为 user 

e 添加 一 个 x.y.Registration 实例 ， 为 其 生成 的 名 称 为 registration 

e 添加 一 个 x.y.Foo 实例 ， 为 其 生成 的 名 称 为 foo 

e 添加 一 个 java.util.HashMap 实例 ， 为 其 生成 的 名 称 为 hashMap 。 这 种 情况 下 ， 显 式 地 声 
明 一 个 键 名 可 能 更 好 ， 因 为 hashMap 的 约定 并 非 那 么 符合 直觉 

e 添加 一 个 null 值 将 导致 程序 抛 出 一 个 IllegalArgumentException 参数 非 法 异常 i 若 你 所 
添加 的 (多 个 ) 对 象 有 可 能 为 null 值 ， 那 你 也 需要 显 式 地 指定 它们 ) 的 名 字 


啥 ? 键 名 不 能 自动 变 复数 形式 么 ? 


Spring Web MVC 的 约定 优 于 配置 支持 尚 不 能 支持 自动 复数 转换 。 这 意思 是 ， 你 不 能 期 望 
往 ModelAndview 中 添加 一 个 person 对 象 的 List 列表 时 ， 框 架 会 自动 为 其 生成 一 个 名 
称 people ° 


这 个 决定 是 经 过 许多 争论 后 的 结果 ， 最 终 “ 最 小 惊喜 原则 "胜出 并 为 大 家 所 接受 。 


为 集合 set RAK List 生成 键 名 所 采取 的 策略 ， 是 先 检 查 集合 的 元 素 类 型 、 拿 到 第 一 个 对 
象 的 短 类 名 ， 然 后 在 其 后 面 添加 List 作为 名 称 。 添 加 数组 对 象 也 是 同 理 ， 尽 管 对 于 数组 我 们 
就 不 需 再 检查 数组 内 容 了 。 下 面 给 出 的 几 个 例子 可 以 阐释 一 些 东西 ， 让 集合 的 名 称 生成 语义 
变 得 更 加 清晰 : 


© 添加 一 个 带 零 个 或 多 个 x.y.User 元 素 类 型 的 数组 x.y.User[] ， 为 其 生成 的 键 名 
是 userList 

© 添加 一 个 带 零 个 或 多 个 x.y.User 元 素 类 型 的 数组 x.y.Foo[] ， 为 其 生成 的 键 名 
是 fooList 

° 添加 一 个 带 零 个 或 多 个 x.y.User 元 素 类 型 的 数组 java.util.ArrayList ， 为 其 生成 的 键 名 
是 userList 

© 添加 一 个 带 零 个 或 多 个 x.y.Foo 元 素 类 型 的 数组 java.util.Hashset ， 为 其 生成 的 键 名 

是 fooList 

一 个 空 的 java.util.ArrayList 则 根本 不 会 被 添加 





21.13.3 视图 -请 求 与 视图 名 的 映射 


RequestToViewNameTranslator 接口 可 以 在 逻辑 视图 名 未 被 显 式 提供 的 情况 下 ， 决 定 一 个 可 用 
的 逻辑 视图 View 名 。 


DefaultRequestToViewNameTranslator 能 够 将 请 求 URL 映 射 到 逻辑 视图 名 上 去 ， 如 下 面 代码 例 
子 所 示 : 


public class RegistrationController implements Controller { 


public ModelAndView handleRequest(HttpServletRequest request, HttpServletResponse 
response) { 
// 处 理 请 求 …. 
ModelAndView mav = new ModelAndView(); 
// 向 Mode1 中 添加 需要 的 数据 
return mav; 
// 请 注意 这 里 ， 没 有 设置 任何 View 对 象 或 逻辑 视图 名 


<?xml version="1.0" encoding="UTF-8"?> 

<beans xmlns="http://www.springframework.org/schema/beans" 
xmlns:xsi="http: //www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation=" 


http://www. springframework.org/schema/beans 
http://www. springframework.org/schema/beans/spring-beans.xsd"> 


<!-- RARA PRM beanktA RI AWERMAS --> 
<bean id="viewNameTranslator" class="org.springframework.web.servlet.view.DefaultR 
equestToViewNameTranslator"/> 


<bean class="x.y.RegistrationController"> 
<!-- 如 果 需 要 ， 注 入 依赖 --> 


</bean> 


<!-- 请 请 求 URL 了 映射 到 控制 器 名 --> 
<bean class="org.springframework.web.servlet.mvc.support.ControllerClassNameHandle 
rMapping"/> 


<bean id="viewResolver" class="org.springframework.web.servlet.view. InternalResour 
ceViewResolver'"> 


<property name="prefix" value="/WEB-INF/jsp/"/> 
<property name="suffix" value=".jsp"/> 
</bean> 


</beans> 


请 注意 在 handleRequest(...) 方法 实现 中 ， 返 回 的 modelandview 对 象 上 自始至终 未 设置 任 

何 view 对 象 或 逻辑 视图 名 。 这 是 由 DefaultRequestToViewNameTranslator 完成 的 ， 它 的 任务 就 
是 从 请 求 的 URL 中 生成 一 个 逻辑 视图 名 。 在 上 面 的 例子 中 ， Registrationcontroller 与 配置 
的 ControllerClassNameHandlerMapping 一 起 使 用 的 结果 是 ， 一 个 URL 

A <http://localhost/registration.html> 的 请 求 ， 会 经 

由 DefaultRequestToViewNameTranslator 生成 并 对 应 到 一 个 逻辑 视图 名 registration bo KY 


辑 视 图 名 又 会 由 InternalResourceviewResolver bean 解 析 到 /weB-INF/jsp/registration.jsp 视 
图 上 。 


你 无 需 显 式 地 定义 一 个 DefaultRequestToViewNameTranslator bean ° w R RU 
的 DefaultRequestToViewNameTranslator 配置 已 能 满足 你 的 需 求 ， 那么 你 无 需 配 置 ， 
Spring Web MVC 的 Dispatcherservlet 会 为 你 实例 化 这 样 一 个 默认 的 对 象 。 


当然 ， 如 果 你 需要 更 改 默认 的 设置 ， 那 你 就 需要 手动 地 配置 自己 
的 DefaultRequestToviewNameTranslator bean。 关 于 可 配置 属性 的 一 些 详细 信息 ， 你 可 以 去 咨 


询 DefaultRequest ToViewNameTranslator 类 详细 的 java 文 档 8 


NO 


21.14 HTTP & XH 


一 个 好 的 HTTP 缓 存 策略 可 以 极 大 地 提高 一 个 web 应 用 的 性 能 及 客户 端的 体验 。 谈 到 HTTP 缓 
存 ， 它 主要 是 与 HTTP 的 响应 头 'cache-control! 相关 ， 其 次 另外 的 一 些 响 应 头 比 如 'Last- 
Modified' 和 'ETag' 等 也 会 起 一 定 的 作用 。 


HTTP 的 响应 头 'cache-control' 主要 帮助 私有 缓存 (比如 浏览 器 端 缓存 ) 和 公共 缓存 (比如 
代理 端 缓存 ) 了 解 它们 应 该 如 果 缓 存 HTTP 响 应 ， 以 便 后 用 。 


ETag (实体 标签 ) 是 一 个 HTTP 响 应 头 ， 可 由 支持 HTTP/1.1 的 web 应 用 服务 器 设置 返回 ， 主 

要 用 于 标识 给 定 的 URL 下 的 内 容 有 无 变化 。 可 以 认为 它 是 Last-Modified 头 的 一 个 更 精细 的 后 
续 版 本 。 当 服务 器 端 返回 了 一 个 ETag 头 的 资源 表示 时 ， 客 户 端 就 可 以 在 后 续 的 GET 请 求 中 使 
用 这 个 表示 ， 一 般 是 将 它 放 在 If-None-Match 请 求 头 中 2 此 时 若 内 容 没 有 变化 ， 服务 器 端 会 直 


接 返 回 304: 内 容 未 更 改 ° 


这 一 节 将 讲解 其 他 一 些 在 Spring Web MVC 应 用 中 配置 HTTP 缓 存 的 方法 。 


21.14.1 HTTP 请 求 头 Cache-Control 


Spring MVC 提 供 了 许多 方式 来 配置 "Cache-Control" 请 求 头 ， 支 持 在 许多 场景 下 使 用 它 。 关 于 
该 请 求 头 完整 详尽 的 所 有 用 法 ， 你 可 以 参考 RFC 7234 的 第 5.2.2 小 节 ， 这 里 我 们 只 讲解 最 常用 
的 几 种 用 法 。 


Spring MVC 的 许多 API 中 都 使 用 了 这 样 的 惯例 配置 : setcachePeriod(int seconds) ， 若 返回 
值 为 : 


e。 -1 ， 则 框架 不 会 生成 一 个 'cache-control' 缓存 控制 指令 响应 头 
e o >H 指示 禁止 使 用 缓存 ， 服务 器 端 Hi i 返回 缓存 控 制 a> "Cache-Control: no-store' 
o 任何 n > 0 的 值 ， 则 响应 会 被 缓存 n 秒 ， 并 返回 缓存 控制 指令 'cache-control: max- 


age=n' 
CacheControl 构造 器 类 被 简单 的 用 来 描述 "Cache-Control" 缓 存 控 制 指 令 ， 使 你 能 更 容易 地 创 


建 自己 的 HTTP 缓 存 策略 。 创 建 守 了 以 后 ， cachecontrol 类 的 实例 就 可 以 在 Spring MVC 的 许 
多 API 中 被 传 入 为 方法 参数 了 。 


// 缓存 一 小 时 "Cache-Control: max-age=3600" 


CacheControl ccCacheOneHour = CacheControl.maxAge(i1, TimeUnit.HOURS) ; 


// ite - "Cache-Control: no-store" 


CacheControl ccNoStore = CacheControl.noStore(); 





// “Cache-Control: max-age=864000, public, no-transform" 
CacheControl ccCustom = CacheControl.maxAge(10, TimeUnit.DAYS) 
.noTransform().cachePublic(); 


21.14.2 对 静态 资源 的 HTTP 绥 存 支持 


为 优化 站 点 性 能 ， 静 态 资 源 应 该 带 有 恰当 的 'cache-control' 值 与 其 他 必要 的 头 。 配 置 一 

个 ResourceHttpRequestHandler 处 理 器 服务 静态 资源 请 求 不 仅 会 读 取 文 件 的 元 数据 并 卉 

充 'Last-Modified' 头 的 值 ， 正 确 配 置 时 'cache-Control' 头 也 会 被 填充。 【这 段 翻 得 还 不 是 
很 清晰 】 


你 可 以 设置 ResourceHttpRequestHandler 上 的 cachePeriod 属性 值 ， 或 使 用 一 
个 cachecontrol 实例 来 支持 更 细致 的 指令 : 


@Configuration 
@EnableWebMvc 
public class WebConfig extends WebMvcConfigurerAdapter { 


@Override 
public void addResourceHandlers(ResourceHandlerRegistry registry) { 
registry.addResourceHandler("/resources/**") 
.addResourceLocations("/public-resources/") 
.setCacheControl(CacheControl.maxAge(1, TimeUnit.HOURS) .cachePublic() ) 


XML 中 写法 则 如 下 : 


<mvc:resources mapping="/resources/**" location="/public-resources/"> 
<mvc:cache-control max-age="3600" cache-public="true"/> 
</mvc: resources> 


21.14.3 在 控制 器 中 设置 Cache-Control ` 
ETag#-Last-Modified"4 & + 


控制 器 和 Bab SE at Ay "Cache-Control' `œ 'ETag' 及 /或 'If-Modified-Since' 头 的 请 求 ， 如 果 服 
务 3 oe 中 设置 了 'cache-control' 响应 头 ， 那 么 我 们 推荐 在 控制 器 内 对 这 些 请 求 头 进行 处 
理 。 这 涉及 一 些 工 作 : 计算 最 后 更 改 时 间 long 和 /或 请 求 的 ETag 值 、 与 请 求 头 的 'Tf- 
Modified-Since' 值 做 比较 ， 并 且 在 资源 未 更 改 的 情况 下 在 响应 中 返回 一 个 304 (资源 未 更 改 ) 
状态 码 。 
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正如 在 "使 用 HttpEntity" 一 节 中 所 讲 ， 控 制 器 可 以 通过 HttpEntity 类 与 请 求 / 响 应 交互 。 返 
回 ResponseEntity 的 控制 器 可 以 在 响应 中 包含 HTTP 缓 存 的 信息 ， 如 下 代码 所 示 : 


@RequestMapping("/book/{id}") 
public ResponseEntity<Book> showBook(@PathVariable Long id) { 


Book book = findBook(id); 
String version = book.getVersion(); 


return ResponseEntity 


.ok() 

| maxAge(30, TimeUnit.DAYS) ) 
.eTag(version) // 这 里 也 能 操作 最 后 修改 时 间 lastModified， 只 不 过 没有 一 一 展 亡 
. body (book); 


这 样 做 不 仅 会 在 响应 头 中 设置 'ETag' 及 'cache-control' 相关 的 信 
状态 码 设 置 为 HTTP 304 Not Modified (资源 未 修改 ) 及 将 响应 体 置 空 
请 求 头 信 息 与 控制 器 设置 的 缓存 信息 能 够 匹配 的 话 。 


息 ， 同 时 也 会 尝试 将 响应 
空 一 如果 客 户 端 携带 的 





boR AZE @RequestMapping 方法 上 也 能 完成 同样 的 事 ， 那 么 以 这 样 做 : 


@RequestMapping 
public String myHandleMethod(WebRequest webRequest, Model model) { 


long lastModified = // 1. 应 用 相关 的 方式 计算 得 到 (application-specific calculation) 
if (request.checkNotModified(lastModified)) { 


// 2. dea 
return null; 





出 不 需要 更 多 处 理 了 
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// 3. 若 资源 更 改 了 ， 那 么 再 进行 请 求 处 理 阶 段 ， 一 般 而 言 是 准备 响应 内 容 
model.addAttribute(...); 
return "myViewName"; 


这 里 最 重要 的 两 个 地 方 是 : 调用 request .checkNotModified(lastModified) 方法 ， 以 及 返 
E null 。 前 者 (方法 调用 ) 在 返回 true 之 前 会 ee 码 设 为 304 ; 而 后 者 ， 在 检查 是 
和 否 更 改 的 方法 调用 返回 true 的 基础 上 直接 将 方法 返 这 会 通知 Spring MVC 不 再 对 请 求 做 
任何 处 理 。 


另外 要 注意 的 是 ， 检 查 资 源 是 否 发 生 了 更 改 有 3 种 方式 : 


® request.checkNotModified(lastModified) 方法 会 将 传 入 的 参数 值 (最 后 修改 时 间 ) 与 请 
RK 'If-Modified-since' 的 值 进行 比较 

e request.checkNotModified(eTag) 方法 会 将 传 入 的 参数 值 与 请 求 头 'ETag' 的 值 进行 比较 

e request.checkNotModified(eTag, lastModified) 方法 会 同时 进行 以 上 两 种 比较 。 也 即 是 
说 ， 只 有 在 两 个 比较 都 被 判定 为 未 修改 时 ， 服 务 器 才 会 返回 一 个 304 响 应 状态 码 HTTP 304 
Not Modified (资源 未 修改 ) 


21.14.4 33ETag (Shallow ETag) 


对 ETag 的 支持 是 由 Servlet 的 过 滤器 shallowEtagHeaderFilter 提供 的 。 它 是 纯 Servlet 技 术 实 现 
的 过 滤器 ， 因 此 ， 它 可 以 与 任何 web 框架 无 缝 集成 。 shallowEtagHeaderFilter 过 滤器 会 创建 
一 个 我 们 称 为 弱 ETag〈 与 强 ETag 相 对 ， 后 面 会 详 述 ) 的 对 象 。 过 滤器 会 将 泻 染 的 JSP 页 面 的 
AS ( 包括 其 他 类 型 的 内 容 ) 缓存 起 来 ， 然 后 以 此 生成 一 个 MD5 哈 希 值 ， 并 把 这 个 值 作为 
ETag 头 的 值 写 回响 应 中 。 下 一 次 客户 端 再 次 请 求 这 个 同样 的 资源 时 ， 它 会 将 这 个 ETag 的 值 写 
到 If-None-Match 头 中 。 过 滤器 会 检测 到 这 个 请 求 头 ， 然 后 再 次 把 视图 泻 染 出 来 并 比较 两 个 哈 
希 值 。 如 果 比 较 的 结果 是 相同 的 ， 那 么 服务 器 会 返回 一 个 304 。 正 如 你 所 见 ， 视 图 仍然 会 被 
泻 染 ， 因 此 本 质 上 这 个 过 滤器 并 非 节省 任何 计算 资源 。 唯 一 节省 的 东西 ， 是 带宽 ， 因 为 被 泻 
染 的 响应 不 会 被 整个 发 送 回 客户 端 。 


请 注意 ， 这 个 策略 节省 的 是 网 络 带 宽 ， 而 非 CPU。 因 为 对 于 每 个 请 求 ， 完 整 的 响应 仍然 需要 
被 整个 计算 出 来 。 而 其 他 在 控制 器 层级 实现 的 策略 (上 几 节 所 述 的 ) 可 以 同时 节省 网 络 带宽 
及 避免 多 余 计算 。 


你 可 以 在 web.xml 中 配置 ShallowEtagHeaderFilter 


<filter 
<filter-name>etagFilter</filter -name> 
<filter-class>org.springframework.web.filter.ShallowEtagHeaderFilter</filter-class> 


</filter> 
<filter -mapping> 
<filter -name>etagFilter</filter-name> 


<servlet -name>petclinic</servlet -name> 
</filter-mapping> 


ee ee 


如 果 是 在 Servlet 3.0 以 上 的 环境 下 ， 可 以 这 么 做 : 


public class MyWebAppInitializer extends AbstractDispatcherServletInitializer { 
bs ate 


@Override 
protected Filter[] getServletFilters() { 
return new Filter[] { new ShallowEtagHeaderFilter() }; 


5) ETag 


更 多 配置 细节 ， 请 参考 第 21.15 基于 代码 的 Servlet 容 器 初始 化 一 小 节 。 
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21.15 RT A 4 Servlet & 7746 1b 


在 Servlet 3.0 以 上 的 环境 下 ， 你 可 以 通过 编程 的 方式 来 配置 Servlet 容 器 了 。 你 可 以 完全 放 
弃 web.xml ， 也 可 以 两 种 配置 方式 同时 使 用 。 以 下 是 一 个 注册 pispatcherservlet 的 例子 : 


import org.springframework.web.WebApplicationInitializer; 
public class MyWebApplicationInitializer implements WebApplicationInitializer { 


@Override 

public void onStartup(ServletContext container) { 
XmlWebApplicationContext appContext = new XmlwebApplicationContext(); 

appContext.setConfigLocation("/WEB-INF/spring/dispatcher-config.xml"); 


ServletRegistration.Dynamic registration = container.addServlet("dispatcher", 
new DispatcherServlet(appContext) ); 


registration.setLoadOnStartup(1); 
registration.addMapping("/"); 


Spring MVC 提 供 了 一 个 webApplicationInitializer 接口 ， 实 现 这 个 接口 能 保证 你 的 配置 能 自 
动 被 检测 到 并 应 用 于 Servlet 3 容器 的 初始 化 中 。 webApplicationInitializer 有 一 个 实现 ， 是 
一 个 抽象 的 基 类 ， 名 字 叫 AbstractDispatcherServletInitializer ° 有 了 它 ， 要 配 

置 Dispatcherservlet 将 变 得 更 简单 ， 你 只 需要 履 写 相应 的 方法 ， 在 其 中 提供 servlet 映 

Ät ` DispatcherServlet 所 需 配置 的 位 置 即 可 : 


public class MyWebAppInitializer extends AbstractAnnotationConfigDispatcherServletinit 
ializer { 


@Override 
protected Class<?>[] getRootConfigClasses() { 
return null; 


@Override 
protected Class<?>[] getServletConfigClasses() { 
return new Class[] { MyWebConfig.class }; 


@Override 
protected String[] getServletMappings() { 
return new String[] { "/" }; 


以 上 的 例子 适用 于 使 用 基于 Java 配 置 的 Spring 应 用 。 如 果 你 使 用 的 是 基于 XML 的 Spring 配置 


方式 ， 那 么 请 直接 继承 abstractDispatcherServletInitializer 这 个 类 : 


public class MyWebAppInitializer extends AbstractDispatcherServletInitializer { 


@Override 
protected WebApplicationContext createRootApplicationContext() { 
return null; 


@Override 

protected WebApplicationContext createServletApplicationContext() { 
XmlWebApplicationContext cxt = new XmlWebApplicationContext(); 
cxt.setConfigLocation("/WEB-INF/spring/dispatcher -config.xm1l"); 
return cxt; 


@Override 
protected String[] getServletMappings() { 
return new String[] { "/" }; 


AbstractDispatcherServletinitializer 同样 也 提供 了 便捷 的 方式 来 添加 过 滤器 Filter 实例 并 
使 他 们 自动 被 映射 到 DispatcherServlet 下 : 


public class MyWebAppInitializer extends AbstractDispatcherServletInitializer { 


Hf 


@Override 
protected Filter[] getServletFilters() { 
return new Filter[] { new HiddenHttpMethodFilter(), new CharacterEncodingFilte 
r() 3; 
} 


每 个 过 滤器 被 添加 时 ， 默 认 的 名 称 都 基于 其 类 类 型 决定 ， 并 且 它 们 会 被 自动 地 映射 
到 Dispatcherservlet F ° 


关于 异步 支持 ” AbstractDispatcherServletInitializer 的 保护 方法 isAsyncSupported 提供 了 
一 个 集中 的 地 方 来 开关 DispatcherServlet 上 的 这 个 配置 ， 它 会 对 所 有 映射 到 这 个 分 发 器 上 的 
过 滤器 生效 。 默 认 情 况 下 ， 这 个 标志 被 设 为 true ° 


最 后 ， 如 果 你 需要 对 DispatcherServlet 做 进一步 的 定制 ， 你 可 以 履 


写 createDispatcherServlet 这 个 方法 。 


21.16 配置 Spring MVC 


21.2.1 WebApplicationContext 中 特殊 的 bean 类 型 小 节 和 21.2.2 默认 的 DispatcherServlet 配 置 
小 节 解 释 了 何谓 Spring MVC 的 特殊 bean， 以 及 Dispatcherservlet 所 使 用 的 默认 实现 。 在 这 
小 节 中 ， 你 将 了 解 配 置 Spring MVC 的 其 他 两 种 方式 : MVC Java 编 程 配置 ， 以 及 MVC XML 命 
名 空间 。 


MVC Java 编 程 配 置 和 MVC 命 名 空间 都 提供 了 相似 的 默认 配置 ， 以 履 写 Dispatcherservlet 的 
默认 值 。 目 标 在 于 为 大 多 数 应 用 软件 免 去 创建 相同 配置 的 麻烦 ， 同 时 也 想 为 配置 Spring MVC 
提供 一 个 更 易 理解 的 指南 、 一 个 简单 的 开始 点 ， 它 只 需要 很 少 或 不 需 任何 关于 底层 配置 的 知 


识 。 
你 可 以 选用 MVC Java 编 程 配 置 或 MVC 命 名 空间 的 方式 ， 这 完全 取决 于 你 的 喜好 。 若 你 能 读 完 


后 pe 小 节 ， 你 会 发 现 使 用 MVC Java 编 程 配置 的 方式 能 更 容易 看 到 底层 具体 的 配置 项 ， 并 且 
EE 对 创建 的 Spring MVC bean 有 更 细 粒 度 的 定制 空间 。 不 过 ， 我 们 还 是 从 头 来 看 起 吧 。 


21.16.1 启用 MVC Java 编 程 配 置 或 MVC 命 名 


空间 


È AMVC Java 编 程 配置 ， 你 需要 在 其 中 一 个 注解 了 @configuration 的 类 上 添 
加 @EnablewebMvc 注解 : 


@Configuration 
@EnableWwebMvc 
public class WebConfig { 


要 启用 XML 命 名 空间 ， 请 在 你 的 DispatcherServlet 上 下 文中 (如果 没有 定义 任何 
DispatcherServlet 上 下 文 ， 那 么 就 在 根 上 下 文中 ) 添加 一 个 mvc:annotation-driven 元 素 : 


<?xml version="1.0" encoding="UTF-8"?> 
<beans xmlns="http://www.springframework.org/schema/beans" 
xmlns:mvc="http://www.springframework.org/schema/mvc" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema- instance" 
xsi:schemaLocation=" 
http://www. springframework.org/schema/beans 
http://www. springframework.org/schema/beans/spring-beans. xsd 
http://www. springframework.org/schema/mvc 
http://www. springframework.org/schema/mvc/spring-mvc.xsd"> 


<mvc:annotation-driven/> 


</beans> 


上 面 的 简单 的 声 明代 码 ， 就 已 经 默认 注册 了 一 个 RequestMappingHandlerMapping ` 一 
个 RequestMappingHandlerAdapter ， 以 及 一 个 ExceptionHandlerExceptionResolver ， VA 支持 对 
使 用 了 @RequestMapping ` @ExceptionHandler 及 其 他 注解 的 控制 器 方法 的 请 求 处 理 。 


同时 ， 上 面 的 代码 还 启用 了 以 下 的 特性 : 


1. Spring 3 风格 的 类 型 转换 支持 。 这 是 使 用 一 个 配置 的 转换 服务 ConversionService 实 例 ， 
以 及 the JavaBeans PropertyEditors used for Data Binding. 

2. 使 用 @NumberFormat 对 数字 字段 进行 格式 化 2 类 型 转换 由 ConversionService 实现 

3. 使 用 @DateTimeFormat 注解 对 Date ` Calendar ` Long A Joda Time 类 型 的 字段 进行 格 
式 化 

4. 使 用 evalid 注解 对 @controller 输入 进行 验证 
JSR-303 规 范 的 验证 器 





前 提 是 classpath 路 径 下 比如 提供 符合 


5. 


HTTP 消 息 转换 HttpMessageConverter 的 支持 ， 对 注解 
了 @RequestMapping 或 @ExceptionHandler 方法 的 @RequestBody 方法 参数 
或 @ResponseBody 返回 值 生效 


下 面 给 出 了 一 份 由 mvc:annotation-driven 注册 可 用 的 HTTP 消 息 转 换 器 的 完整 列表 : 


1. 转换 字 节 数组 的 ByteArrayHttpMessageConverter 


10. 


转换 字符 串 的 StringHttpMessageConverter 

ResourceHttpMessageConverter : org.springframework.core.io.Resource 与 所 有 媒体 类 型 
之 间 的 互相 转换 

SourceHttpMessageConverter :从 (到) javax.xml.transform.Source 的 转换 
FormHttpMessageConverter : 数据 与 MultiValueMap<String, String> 之 间 的 互相 转换 
Jaxb2RootElementHttpMessageConverter : Java 对 象 与 XML 之 间 的 互相 转换 该 转换 器 
在 classpath 路 径 下 有 JAXB2 依 赖 并 且 没有 Jackson 2 XML 扩展 时 被 注册 
该 转换 器 在 classpath 








MappingJackson2HttpMessageConverter : 从 (到 ) JSON 的 转换 
下 有 Jackson 2 依赖 时 被 注册 
MappingJackson2XmlHttpMessageConverter : 从 (到 ) XML 的 转换 
classpath 下 有 Jackson 2 XML 扩展 时 被 注册 





该 转换 器 在 








AtomFeedHttpMessageConverter : Atom 源 的 转换 该 转换 器 在 classpath 路 径 下 有 Rome 
时 被 注册 

RssChannelHttpMessageConverter : RSS 源 的 转换 该 转换 器 在 classpath 路 径 下 有 
Rome 时 被 注册 


你 可 以 参考 21.16.12 消息 转换 器 一 小 节 ， 了 解 如 何 进一步 定制 这 些 默 认 的 转换 器 。 


Jackson JSON 和 XML 转换 器 是 通过 Jackson20bjectMapperBuilder 创建 
的 objectMapper 实例 创建 的 ， 目 的 在 于 提供 更 好 的 默认 配置 


该 builder 会 使 用 以 下 的 默认 属性 对 Jackson 进 行 配置 : 


1. 禁用 DeserializationFeature.FAIL _ON_UNKNOWN_PROPERTIES 

2. #571 MapperFeature.DEFAULT_VIEW_INCLUSION 

同时 ， 如 果 检 测 到 在 classpath 路 径 下 存在 这 些 模块 ， 该 builder 也 会 自动 地 注册 它们 : 
1. jackson-datatype-jdk7: 支持 Java 7 的 一 些 类 型 ， 例 如 java.nio.file.Path 

2. jackson-datatype-joda: 支持 Joda-Time 类 型 

3. jackson-datatype-jsr310: 支持 Java 8 的 Date & Time API 类 型 


4. jackson-datatype-jdk8: 支持 Java 8 其 他 的 一 些 类 型 ， 比 如 optional 等 


启用 MVC Java 编 程 配置 或 MVC 命 名 空间 
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21.16.2 默认 配置 的 定制 化 


在 MVC Java 编 程 配置 方式 下 ， 如 果 你 想 对 默认 配置 进行 定制 ， 你 可 以 自己 实 
IL WebMvcConfigurer 接口 ， 要 么 继承 webmvcConfigurerAdapter 类 并 徐 写 你 需要 定制 的 方法 : 


@Configuration 
@EnableWebMvc 
public class WebConfig extends WebMvcConfigurerAdapter { 


// Override configuration methods... 


在 MVC XML 命名 空间 下 ， 如 果 你 想 对 默认 配置 进行 定制 ， 请 查看 <mvc:annotation- 
driven/> 元 素 支 持 的 属性 和 子 元素 。 你 可 以 查看 Spring MVC XML schema， 或 使 用 IDE 的 自 
动 补 全 功能 来 查看 有 哪些 属性 和 子 元 素 是 可 以 配置 的 。 


21.16.3 转换 与 格式 化 


数字 的 Number 类 型 和 日 期 Date 类 型 的 格式 化 是 默认 安装 了 的 2 包括 @NumberFormat 注解 
和 @DateTimeFormat 注解 。 如 果 classpath 路 径 下 存在 Joda Time 人 依赖， 那么 完美 支持 Joda 
Time 的 时 间 格 式 化 库 也 会 被 安装 好 。 如 果 要 注册 定制 的 格式 化 器 或 转换 器 ， 请 履 

写 addFormatters 方法 : 


@Configuration 
@EnablewebMvc 
public class WebConfig extends WebMvcConfigurerAdapter { 


@Override 
public void addFormatters(FormatterRegistry registry) { 
// Add formatters and/or converters 


使 用 MVC 命 名 空间 时 ， <mvc:annotation-driven> 也 会 进行 同样 的 默认 配置 。 要 注册 定制 的 格 
式 化 器 和 转换 器 ， 只 需要 提供 一 个 转换 服务 conversionservice 


转换 与 格式 化 


<?xml version="1.0" encoding="UTF-8"?> 
<beans xmlns="http://www.springframework.org/schema/beans" 
xmlns:mvc="http://www.springframework.org/schema/mvc" 
xmlns:xsi="http: //www.w3.org/2001/XMLSchema-instance" 
xSi:schemaLocation=" 
http://www. springframework.org/schema/beans 
http://www. springframework.org/schema/beans/spring-beans. xsd 
http://www. springframework.org/schema/mvc 
http://www. springframework.org/schema/mvc/spring-mvc.xsd"> 


<mvc:annotation-driven conversion-service="CconversionService"/> 


<bean id="conversionService" 
class="org.springframework.format.support.FormattingConversionServiceFacto 
ryBean"> 
<property name="Converters"> 
<set> 
<bean class="org.example.MyConverter"/> 
</set> 
</property> 
<property name="formatters"> 
<set> 
<bean class="org.example.MyFormatter"/> 
<bean class="org.example.MyAnnotationFormatterFactory"/> 
</set> 
</property> 
<property name="formatterRegistrars"> 
<set> 
<bean class="org.example.MyFormatterRegistrar"/> 
<7, Set> 
</property> 
</bean> 


</beans> 


关于 如 何 使 用 格式 化 管理 器 FormatterRegistrar， 请 参考 8.6.4 FormatterRegistrar SPI— 


节 > VAR Format tingConversionServiceFactoryBean 的 文档 8 
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21.16.4 验证 


Spring 提供 了 一 个 验证 器 Validator 接 口 ， 应 用 的 任何 一 层 都 可 以 使 用 它 来 做 验证 。 在 Spring 
MVC 中 ， 你 可 以 配置 一 个 全 局 的 validator 实例 ， 用 以 处 理 所 有 注解 了 evalid 的 元 素 或 注解 
了 @validated 的 控制 器 方法 参数 、 以 及 /或 在 控制 器 内 的 @InitBinder 方法 中 用 作 局 部 

的 validator 。 全 局 验证 器 与 局 部 验证 器 实例 可 以 结合 起 来 使 用 ， 提 供 组 合 验 证 。 


Spring 还 支持 JSR-303/JSR-349 的 Bean 验 证 。 这 是 通过 LocalvalidatorFactoryBean 类 实现 
的 ， 它 为 Spring 的 验证 器 接口 org.springframework.validation.Validator 到 Bean 验 证 

的 javax.validation.Validator 接口 做 了 适 配 。 这 个 类 可 以 插入 到 Spring MVC 的 上 下 文中 ， 
作为 一 个 全 局 的 验证 器 ， 如 下 所 述 。 


如 果 在 classpath 下 存在 Bean 验 证 器 ， 诸 如 Hibernate Validator 等 ， 那 
么 @EnablewebMvc 或 <mvc:annotation-driven> 默认 会 自动 使 用 LocalvalidatorFactoryBean 为 
Spring MVC 应 用 提供 Bean 验 证 的 支持 。 


有 时 ， 能 将 LocalvalidatorFactoryBean 直接 注入 到 控制 器 或 另外 一 个 类 中 会 更 方便 。 


Sometimes it's convenient to have a LocalvalidatorFactoryBean injected into a 
controller or another class. The easiest way to do that is to declare your own @Bean 
and also mark it with @Primary in order to avoid a conflict with the one provided with 
the MVC Java config. 


If you prefer to use the one from the MVC Java config, you'll need to override the 
mvcValidator method from webmvcConfigurationSupport and declare the method to 
explicitly return LocalvalidatorFactory rather than validator . See Section 21.16.13, 
"Advanced Customizations with MVC Java Config" for information on how to switch to 
extend the provided configuration. 


此 外 ， 你 也 可 以 配置 你 自己 的 全 局 validator 验证 器 实例 : 


@Configuration 
@EnableWebMvc 
public class WebConfig extends WebMvcConfigurerAdapter { 


@Override 
public Validator getValidator(); { 
// return "global" validator 


} 


XML 中 做 法 如 下 : 


<?xml version="1.0" encoding="UTF-8"?> 
<beans xmlns="http://www.springframework.org/schema/beans" 
xmlns:mvc="http://www.springframework.org/schema/mvc" 
xmlns:xsi="http: //www.w3.org/2001/XMLSchema- instance" 
xsi:schemaLocation=" 
http://www. springframework.org/schema/beans 
http://www. springframework.org/schema/beans/spring-beans. xsd 
http://www. springframework.org/schema/mvc 
http://www. springframework.org/schema/mvc/spring-mvc.xsd"> 


<mvc:annotation-driven validator="globalValidator"/> 


</beans> 


若 要 同时 使 用 全 局 验证 和 局 部 验证 ， 只 需 添 加 一 个 (或 多 个 ) 局 部 验证 器 即 可 : 


@Controller 
public class MyController { 


@InitBinder 
protected void initBinder(WebDataBinder binder) { 
binder .addValidators(new FooValidator()); 


做 完 这 个 最 少 的 配置 之 后 ， 任 何 时 候 只 要 方法 中 有 参数 注解 了 evalid 或 @validated ， 配 置 
的 验证 器 就 会 自动 对 它们 做 验证 。 任 何 无 法 通过 的 验证 都 会 被 自动 报告 为 错误 并 添加 

到 BindingResult 对 象 中 去 ， 你 可 以 在 方法 参数 中 声明 它 并 获取 这 些 错 误 ， 同 时 这 些 错误 也 能 
在 Spring MVC 的 HTML 视 图 中 被 泻 染 。 


21.16.5 拦截 器 


Age 


你 可 以 配置 处 理 器 拦截 器 HandlerInterceptors 或 Web 请 求 拦截 器 webRequestInterceptors 等 
拦截 器 ， 并 配置 它们 拦截 所 有 进入 容器 的 请 求 ， 或 限定 到 符合 特定 模式 的 URL 路 径 。 


在 MVC Java 编 程 配 置 下 注册 拦截 器 的 方法 : 


@Configuration 
@EnablewebMvc 
public class WebConfig extends WebMvcConfigurerAdapter { 


@Override 
public void addInterceptors(InterceptorRegistry registry) { 
registry.addInterceptor(new LocaleInterceptor()); 
registry.addInterceptor(new ThemeInterceptor()).addPathPatterns("/**").exclude 
PathPatterns("/admin/**"); 
registry.addInterceptor(new SecurityInterceptor()).addPathPatterns("/secure/*" 


Ne 


在 MVC XML 命名 空间 下 ， 则 使 用 <mvc:interceptors> 元 素 : 


<mvc:interceptors> 
<bean class="org.springframework.web.servlet.i18n.LocaleChangeInterceptor"/> 
<mvc:interceptor> 
<mvc:mapping path="/**"/> 
<mvc:exclude-mapping path="/admin/**"/> 
<bean class="org.springframework.web.servlet.theme.ThemeChangeInterceptor"/> 
</mvc:interceptor> 
<mvc:interceptor> 
<mvc:mapping path="/secure/*"/> 
<bean class="org.example.SecurityInterceptor"/> 
</mvc:interceptor> 
</mvc:interceptors> 


21.16.6 内 容 协 商 


You can configure how Spring MVC determines the requested media types from the request. 
The available options are to check the URL path for a file extension, check the "Accept" 
header, a specific query parameter, or to fall back on a default content type when nothing is 
requested. By default the path extension in the request URI is checked first and the "Accept" 
header is checked second. 


The MVC Java config and the MVC namespace register json , xml, rss , atom by 
default if corresponding dependencies are on the classpath. Additional path extension-to- 
media type mappings may also be registered explicitly and that also has the effect of 
whitelisting them as safe extensions for the purpose of RFD attack detection (see the 
section called "Suffix Pattern Matching and RFD" for more detail). 


Below is an example of customizing content negotiation options through the MVC Java 
config: 


_@Configuration_ 
_@EnablewebMvc_ 
public class WebConfig extends WebMvcConfigurerAdapter { 


_@Override_ 
public void configureContentNegotiation(ContentNegotiationConfigurer configurer) { 
configurer.mediaType("json", MediaType.APPLICATION_JSON) ; 


In the MVC namespace, the <mvc:annotation-driven> element has a content- negotiation- 
manager attribute, which expects a ContentNegotiationManager that in turn can be created 


with a contentNegotiationManagerFactoryBean 


<mvc:annotation-driven content-negotiation-manager="contentNegotiationManager"/> 


<bean id="contentNegotiationManager" class="org.springframework.web.accept.ContentNego 
tiationManagerFactoryBean"> 
<property name="mediaTypes"> 
<value> 
json=application/json 
xml=application/xml 
</value> 
</property> 
</bean> 


If not using the MVC Java config or the MVC namespace, you'll need to create an instance 

of ContentNegotiationManager and use it to configure RequestMappingHandlerMapping for 

request mapping purposes, and RequestMappingHandlerAdapter and 
ExceptionHandlerExceptionResolver for content negotiation purposes. 


Note that contentNegotiatingViewResolver now can also be configured with a 
ContentNegotiationManager , SO you Can use one shared instance throughout Spring MVC. 


In more advanced cases, it may be useful to configure multiple contentNegotiationManager 
instances that in turn may contain custom contentNegotiationstrategy implementations. For 
example you could configure ExceptionHandlerExceptionResolver witha 
ContentNegotiationManager that always resolves the requested media type to 
"application/json" . Or you may want to plug a custom strategy that has some logic to 
select a default content type (e.g. either XML or JSON) if no content types were requested. 


21.16.7 视图 控制 BS 


以 下 的 一 段 代码 相当 于 定义 一 个 parameterizableViewController 视图 控制 器 的 快捷 方式 ， 该 控 
制 器 会 立即 将 一 个 请 求 转发 (forwards) 给 一 个 视图 。 请 确保 仅 在 以 下 情景 下 才 使 用 这 个 类 : 
当 控 制 器 除了 将 视图 泻 染 到 响应 中 外 不 需要 执行 任何 逻辑 时 。 


以 下 是 一 个 例子 ， 展 示 了 如 何在 MVC Java 编 程 配置 方式 下 将 所 有 "/" 请 求 直 接 转 发 给 名 字 
A "home" 的 视图 : 


@Configuration 
@EnablewebMvc 


public class WebConfig extends WebMvcConfigurerAdapter { 


@Override 
public void addViewControllers(ViewControllerRegistry registry) { 
registry.addViewController("/").setViewName("home"); 


在 MVC XML 命名 空间 下 完成 同样 的 配置 ， 则 使 用 <mvc:view-controller> 元 素 : 


<mvc:view-controller path="/" view-name="home"/> 


21.16.8 视图 解析 器 


MVC 提 供 的 配置 简化 了 视图 解析 器 的 注册 工作 。 


以 下 的 代码 展示 了 在 MVC Java 编 程 配置 下 ， 如 何 为 内 容 协 商 配置 FreeMarker HTML 模 板 和 
Jackson 作 为 JSON 数 据 的 默认 视图 解析 : 


@Configuration 
@EnableWwebMvc 
public class WebConfig extends WebMvcConfigurerAdapter { 


@Override 
public void configureViewResolvers(ViewResolverRegistry registry) { 
registry.enableContentNegotiation(new MappingJackson2JsonView()); 


registry.jsp(); 


在 MVC XML 命名 空间 下 实现 相同 配置 : 


<mvc:view-resolvers> 
<mvc: content -negotiation> 
<mvc: default -views> 
<bean class="org.springframework.web.servlet.view.json.MappingJackson2Json 
View"/> 
</mvc : default -views> 
</mvc: content -negotiation> 
<mvc:jsp/> 
</mvc : view-resolvers> 


需要 注意 的 是 ， 使 用 FreeMarker Velocity, Tiles, Groovy Markup 及 Script 模板 作为 视图 技术 
时 ， 仍 需要 配置 一 些 其 他 选项 。 


MVC 命 名 空间 为 每 种 视图 都 提供 了 相应 的 元 素 。 比 如 下 面 代码 是 FreeMarker 需 要 的 配置 : 


<mvc:view-resolvers> 
<mvc: content -negotiation> 
<mvc : default -views> 
<bean class="org.springframework.web.servlet.view.json.MappingJackson2Json 
View"/> 
</mvc : default -views> 
</mvc: content -negotiation> 
<mvc:freemarker cache="false"/> 
</mvc : view-resolvers> 


<mvc: freemarker -configurer> 
<mvc:template-loader-path location="/freemarker"/> 
</mvc : freemarker -configurer> 


在 MVC Java 编 程 配 置 方式 下 ， 添 加 一 个 视图 对 应 的 “配置 器 "bean 即 可 : 


@Configuration 
@EnableWwebMvc 
public class WebConfig extends WebMvcConfigurerAdapter { 


@Override 

public void configureViewResolvers(ViewResolverRegistry registry) { 
registry.enableContentNegotiation(new MappingJackson2JsonView()); 
registry. freeMarker().cache(false); 


@Bean 

public FreeMarkerConfigurer freeMarkerConfigurer() { 
FreeMarkerConfigurer configurer = new FreeMarkerConfigurer(); 
configurer.setTemplateLoaderPath("/WEB-INF/"); 
return configurer; 


资源 的 服务 


21.16.10 回 到 默认 的 Servlet 来 进行 资源 服务 


这 些 配置 允许 你 将 Dispatcherservlet 映射 到 "/" 路 径 oe 盖 了 容器 默认 Servlet 的 映射 ) > 
但 依然 保留 容器 默认 的 Servlet 以 处 理 静 态 资 源 的 请 求 。 这 可 以 通过 配置 一 个 URL 了 映射 到 "/**" 的 
处 理 器 DefaultservletHttpRequestHandler 来 实现 ， 并 且 该 处 理 器 在 其 他 所 有 URL 了 映射 关系 中 
优先 级 应 该 是 最 低 的 。 


该 处 理 器 会 将 所 有 请 求 转发 (forward) 到 默认 的 Servlet， 因 此 需要 保证 它 在 所 有 URL 处 理 器 
映射 HandlerMappings 的 最 后 。 如 果 你 是 通过 <mvc :annotation-driven> 的 方式 进 并 行 配置 ， 或 自 
己 定 制 了 HandlerMapping 实例 ， 那 么 你 需要 确保 该 处 理 器 order 属性 的 值 


比 DefaultServletHttpRequestHandler 的 次 序 值 Integer .MAXVALUE 小 。 


使 用 默认 的 配置 启用 该 特性 ， 你 可 以 : 


@Configuration 
@EnablewebMvc 
public class WebConfig extends WebMvcConfigurerAdapter { 


@Override 
public void configureDefaultServletHandling(DefaultServletHandlerConfigurer config 
urer) { 
configurer.enable(); 


} 


XML P 命名 空间 只 需 一 行 


<mvc:default-servlet-handler/> 


不 过 需要 注意 ， 履 写 了 "的 Servlet 映 射 后 ， 黑 认 Servlet 的 RequestDispatcher 就 必须 通过 名 字 
而 非 路 径 来 取得 了 。 DefaultServletHttpRequestHandler 会 党 尝试 在 容器 初始 化 的 时 候 自动 检测 
默认 Servlet， 这 里 它 使 用 的 是 一 份 主流 Servlet 容 器 (包括 Tomcat、Jetty、GlassFish、 
JBoss、Resin、WebLogic， 和 WWebSphere ) 已 知 的 名 称 列表 。 如 果 默 认 Servlet 被 配置 了 
一 个 其 他 的 名 字 ， 或 者 使 用 了 一 个 列表 里 未 提供 默认 Servlet 名 称 的 容器 ， 那 么 默认 Servlet 的 
名 称 必 须 被 显 式 指定 。 正 如 下 面 代码 所 示 : 


回 到 默认 的 Servlet 来 进行 资源 服务 


@Configuration 
@EnableWwebMvc 


public class WebConfig extends WebMvcConfigurerAdapter { 


@Override 


public void configureDefaultServletHandling(DefaultServletHandlerConfigurer co 
nhwgucer)) A 


configurer.enable("myCustomDefaultServlet"); 


XML 命名 空间 的 配置 方式 : 


<mvc:default-servlet-handler default-servlet-name="myCustomDefaultServlet"/> 
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21.16.11 路 径 匹 配 


这 些 配置 允许 你 对 许多 与 URL 映 射 和 路 径 匹 配 有 关 的 设置 进行 定制 。 关 于 所 有 可 用 的 配置 选 
项 ， 请 参考 PathMatchConfigurer 类 的 API 文 档 。 


下 面 是 采用 MVC Java 编 程 配置 的 一 段 代码 : 


@Configuration 
@EnablewebMvc 
public class WebConfig extends WebMvcConfigurerAdapter { 


@Override 
public void configurePathMatch(PathMatchConfigurer configurer) { 
configurer 
. setUseSuf fixPatternMatch(true) 
. setUseTrailingSlashMatch(false) 
. setUseRegisteredSuffixPatternMatch( true) 
.setPathMatcher (antPathMatcher()) 
.setUrlPathHelper (urlPathHelper()); 


@Bean 
public UrlPathHelper urlPathHelper() { 
OA 


@Bean 
public PathMatcher antPathMatcher() { 
Web es cera 


在 XML 命名 空间 下 实现 同样 的 功能 ， 可 以 使 用 <mvc:path-matching> 元 素 : 


<mvc:annotation-driven> 
<mvc:path-matching 

suffix-pattern="true" 
trailing-slash="false" 
registered-suffixes-only="true" 
path-helper="pathHelper" 
path-matcher="pathMatcher"/> 

</mvc:annotation-driven> 


<bean id="pathHelper" class="org.example.app.MyPathHelper"/> 
<bean id="pathMatcher" class="org.example.app.MyPathMatcher"/> 


路 径 匹 配 
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21.16.12 消息 转换 器 


使 用 MVC Java 编 程 配置 方式 时 ， 如 果 你 想 替 换 Spring MVC 提 供 的 默认 转换 器 ， 完 全 定制 自 
aay d e SA ATALA configureMessageConverters() 方法 来 实现 。 如 
果 你 只 是 想 定制 一 下 ， 或 者 想 在 默认 转换 器 之 外 再 添加 其 他 的 转换 器 ， 那 么 可 以 通过 黎 

写 extendMessageConverters() 方法 来 实现 。 


下 面 是 一 段 例子 ， 它 使 用 定制 的 objectMapper 构造 了 新 的 Jackson 的 JSON 和 XML 转换 器 ， 并 
用 它们 替换 了 默认 提供 的 转换 器 : 


@Configuration 
@EnableWebMvc 
public class WebConfiguration extends WebMvcConfigurerAdapter { 


@Override 
public void configureMessageConverters(List<HttpMessageConverter<?>> converter 


Jackson20bjectMapperBuilder builder = new Jackson20bjectMapperBuilder ( ) 
. indentOutput (true) 
.dateFormat(new SimpleDateFormat("yyyy-MM-dd")) 
.modulesToInstall(new ParameterNamesModule()); 

converters.add(new MappingJackson2HttpMessageConverter (builder .build())); 

converters.add(new MappingJackson2xXmlHttpMessageConverter(builder.xm1().bu 

ild())); 
} 


在 上 面 的 例子 中 ， gjackson20bjectMapperBuilder 用 于 

为 MappingJackson2HttpMessageConverter 和 MappingJackson2XmlHttpMessageConverter 转换 器 创 
建 公 共 的 配置 ， 比 如 启用 tab 缩 进 、 定 制 的 日 期 格式 ， 并 注册 了 一 个 模块 jackson-module- 
parameter-names 用 于 获取 参数 名 (Java 8 新 增 的 特性 ) 


除了 jackson- dataformat-xml ， 要 启用 Jackson XML 的 tab 缩 进 支 持 ， 还 需要 一 


woodstox-core-asl 依赖 。 


还 有 其 他 有 用 的 Jackson 模 块 可 以 使 用 : 


1. jackson-datatype-money : 提供 了 对 javax.money 类 型 的 支持 ( 非 官方 模块 ) 
2. jackson-datatype-hibernate : 提供 了 Hibernate 相 关 的 类 型 和 属性 支持 (包含 懒 加 载 
aspects) 


在 XML 做 同样 的 事 也 是 可 能 的 : 


消息 转换 器 


<mvc :annotation-driven> 
<mvc :message-converters> 
<bean class="org.springframework.http.converter.json.MappingJackson2HttpMessag 
eConverter"> 
<property name="objectMapper" ref="objectMapper"/> 
</bean> 
<bean class="org.springframework.http.converter.xml.MappingJackson2XmlHttpMess 
ageConverter"> 
<property name="objectMapper" ref="xmlMapper"/> 
</bean> 
</mvc:message-converters> 
</mvc:annotation-driven> 


<bean id="objectMapper" class="org.springframework.http.converter.json.Jackson20bjectM 
apperFactoryBean" 

p:indentOutput="true" 

p:simpleDateFormat="yyyy-MM-dd" 

p:modulesToInstall="com.fasterxml.jackson.module.paramnames.ParameterNamesModule" 
i 


<bean id="xmlMapper" parent="objectMapper" p:createXmlMapper="true"/> 


EE 
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21.16.13 使 用 MVC Java 编 程 进行 高 级 定制 


从 上 面 许多 例子 你 可 以 看 到 ，MVC Java 编 程 配置 和 MVC 命 名 空间 的 方式 都 提供 了 更 高 抽象 层 
级 的 应 用 配置 ， 它 不 需要 你 对 底下 创建 的 bean 有 非常 深 ae > 相反 ， 这 使 得 你 能 仅 专 注 

于 应 用 需要 的 配置 。 不 过 ， 有 时 你 可 能 希望 对 应 用 的 更 精细 控制 ， 或 你 就 是 单纯 希望 理解 底 

下 的 配置 和 机 制 。 


要 做 到 更 精细 的 控制 ， 你 要 做 的 第 一 步 就 是 看 看 底层 都 为 你 创建 了 哪些 bean。 若 你 使 用 MVC 
Java 编 程 的 方式 进行 配置 你 可 以 看 看 java 文 档 ， 以 及 WebMvcConfigurationSupport 类 

的 @Bean 方法 。 这 个 类 有 的 配置 都 会 自动 被 @EnablewebMvc 注解 导入 。 事 实 上 ， 如 果 你 打 

开 @EnablewebMvc 的 声明 ， 你 就 会 看 到 应 用 于 其 上 的 @Import 注解 。 


精细 控制 的 下 一 步 是 选择 一 个 WebMvcconfigurationsupport 创建 的 bean， 定 制 它 的 属性 ， 或 你 
可 以 提供 自己 的 一 个 实例 。 这 确保 做 到 以 下 两 步 : 移 除 @EnablewebMvc 注解 以 避免 默认 配置 被 


自 动 导 入 ， 然 后 继承 DelegatingwebMvcConfiguration 类 ， 它 是 WebMvcConfigurationSupport 的 
peed eu, Seed ee 


@Configuration 


public class WebConfig extends DelegatingWebMvcConfiguration { 


@Override 


public void addInterceptors(InterceptorRegistry registry){ 





Ed ase 

} 

@Override 

@Bean 

public RequestMappingHandlerAdapter requestMappingHandlerAdapter() { 
// 自己 创建 适配器 ， 或 者 调用 Super 让 基 类 处 理 
// 然后 在 这 里 定制 bean 的 一 些 属性 

} 


应 用 应 该 只 有 一 个 继承 DelegatingwebMvcconfiguration 的 配置 类 ， 或 只 有 一 
个 @EnablewebMvc 注解 的 类 ， 因 为 它们 背后 注册 的 bean 都 是 相同 的 。 


使 用 这 个 方式 修改 bean 的 属性 ， 与 这 节 前 面 展示 的 任何 高 抽象 层级 的 配置 方式 并 不 冲 
X o WebMvcConfigurerAdapter 的 子 类 和 WebMvcconfigurer 的 实现 都 还 是 会 被 使 用 。 


21.16.14 使 用 MVC 命 名 空间 进 级 的 定制 化 


如 果 使 用 MVC 命 名 空间 ， 要 在 默认 配置 的 基础 上 实现 粒度 更 细 的 控制 ， 则 要 比 使 用 MVC Java 
编程 配置 的 方式 难 一 些 。 


如 果 你 确实 需要 这 么 做 ， 那 也 尽量 不 要 复制 默认 提供 的 配置 ， 请 尝试 配置 
个 BeanPostProcessor 后 置 处理 器 ， 用 它 来 检测 你 要 定制 的 bean。 可 以 通过 bean 的 类 型 来 
找 ， 找 到 以 后 再 修改 需要 定制 的 属性 值 。 比 如 这 样 : 


@Component 
public class MyPostProcessor implements BeanPostProcessor { 


public Object postProcessBeforeInitialization(Object bean, String name) throws Bea 
nsException { 
if (bean instanceof RequestMappingHandlerAdapter) { 
// 修改 适 = p4 


& Ata 的 属性 


} 


注意 ? MyPostProcessor 需要 被 包含 在 <component scan/> 的 路 径 下 ， 这 样 它 才能 被 自 动 检测 
|; 或 者 你 也 可 以 手动 显 式 地 用 一 个 XML 的 bean 定 义 来 声明 它 。 


